-- Hoogle documentation, generated by Haddock -- See Hoogle, http://www.haskell.org/hoogle/ -- | Haskell interface to Python -- -- MissingPy is two things: -- -- A Haskell binding for many C and Python libraries for tasks such as -- data compression, databases, etc. This can be found in the MissingPy -- module tree. -- -- Also, it's a low-level Haskell binding to the Python interpreter to -- enable development of hybrid applications that use both environments. -- This can be found in the Python module tree. The Haskell bindings -- above use this environment. -- -- MissingPy permits you to call Python code from Haskell. It does NOT -- permit you to call Haskell code from Python. -- -- MissingPy is the companion to my MissingH library, and integrates with -- it. @package MissingPy @version 0.10.6 -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Interfaces to low-level Python types. You should probably not use this -- module directly. You probably want Python.Objects instead. -- -- You'll only need this module directly if you are importing new -- functions from the Python C API. -- -- Written by John Goerzen, jgoerzen@complete.org module Python.Types -- | The type of Python objects. newtype PyObject PyObject :: (ForeignPtr CPyObject) -> PyObject type CPyObject = () -- | The type of Python exceptions. data PyException PyException :: PyObject -> PyObject -> PyObject -> String -> PyException -- | Exception type excType :: PyException -> PyObject -- | Exception value excValue :: PyException -> PyObject -- | Traceback excTraceBack :: PyException -> PyObject -- | Formatted for display excFormatted :: PyException -> String -- | How to interpret a snippet of Python code. data StartFrom Py_eval_input :: StartFrom Py_file_input :: StartFrom Py_single_input :: StartFrom newtype PyGILState PyGILState :: (ForeignPtr CPyGILState) -> PyGILState type CPyGILState = () instance Eq PyObject instance Show PyObject instance Eq PyGILState instance Show PyGILState instance Typeable PyException instance Show PyException -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Python low-level utilities -- -- Written by John Goerzen, jgoerzen@complete.org -- -- Please use sparingly and with caution. The documentation for their -- behavior should be considered to be the source code. module Python.Utils -- | Convert a Ptr CPyObject to a PyObject. fromCPyObject :: Ptr CPyObject -> IO PyObject -- | Uses a PyObject in a function that needs Ptr CPyObject. withPyObject :: PyObject -> (Ptr CPyObject -> IO b) -> IO b -- | Same as withPyObject, but uses nullPtr if the input is Nothing. maybeWithPyObject :: Maybe PyObject -> (Ptr CPyObject -> IO b) -> IO b -- | Called when a Python exception has been detected. It will raise the -- exception in Haskell. raisePyException :: IO a -- | Called to make sure the passed CInt isn't -1. Raise an exception if it -- is. checkCInt :: CInt -> IO CInt -- | Returns the default globals environment. getDefaultGlobals :: IO PyObject -- | Wrapper around C PyImport_AddModule, which looks up an existing module pyImport_AddModule :: String -> IO PyObject -- | Gets the dict associated with a module. pyModule_GetDict :: PyObject -> IO PyObject py_incref :: Ptr CPyObject -> IO () -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Python type instances and object utilities. -- -- For more similar utilities, see Python.Objects.File and -- Python.Objects.Dict. -- -- Written by John Goerzen, jgoerzen@complete.org module Python.Objects -- | The type of Python objects. data PyObject -- | Members of this class can be converted from a Haskell type to a Python -- object. class ToPyObject a toPyObject :: ToPyObject a => a -> IO PyObject -- | Members of this class can be derived from a Python object. class FromPyObject a fromPyObject :: FromPyObject a => PyObject -> IO a -- | Gets the type of a Python object. Same as type(x) in Python. typeOf :: PyObject -> IO PyObject -- | Gets a string representation of a Python object. Same as str(x) in -- Python. strOf :: PyObject -> IO String -- | Gets the Python representation of a Python object. Same as repr(x) in -- Python. reprOf :: PyObject -> IO String -- | Displays a Python object and its type. showPyObject :: PyObject -> IO String -- | Displays a list of keys contained in the Python object. dirPyObject :: PyObject -> IO [String] -- | An interface to a function similar to Python's getattr. This will look -- up an attribute (such as a method) of an object. getattr :: PyObject -> String -> IO PyObject -- | An interface to Python's hasattr. Returns True if the named attribute -- exists; False otherwise. hasattr :: PyObject -> String -> IO Bool -- | An interface to Python's setattr, used to set attributes of an object. setattr :: PyObject -> String -> PyObject -> IO () pyList_AsTuple :: PyObject -> IO PyObject -- | Converts a Python list to a tuple. -- -- Call a Python object (function, etc). -- -- For a higher-level wrapper, see callByName. pyObject_Call :: PyObject -> [PyObject] -> [(String, PyObject)] -> IO PyObject -- | Call a Python object with all-Haskell parameters. Similar to -- PyObject_Call. This limits you to a single item type for the -- regular arguments and another single item type for the keyword -- arguments. Nevertheless, it could be a handy shortcut at times. -- -- For a higher-level wrapper, see callByName. -- -- You may find noParms and noKwParms useful if you aren't -- passing any parameters. pyObject_CallHs :: (ToPyObject a, ToPyObject b, FromPyObject c) => PyObject -> [a] -> [(String, b)] -> IO c -- | Like PyObject_CallHs, but discards the return value. pyObject_RunHs :: (ToPyObject a, ToPyObject b) => PyObject -> [a] -> [(String, b)] -> IO () -- | Calls the named method of the given object. callMethodHs :: (ToPyObject a, ToPyObject b, FromPyObject c) => PyObject -> String -> [a] -> [(String, b)] -> IO c -- | Like callMethodHs, but discards the return value. runMethodHs :: (ToPyObject a, ToPyObject b) => PyObject -> String -> [a] -> [(String, b)] -> IO () noParms :: [String] noKwParms :: [(String, String)] instance [overlap ok] FromPyObject a => FromPyObject [a] instance [overlap ok] ToPyObject a => ToPyObject [a] instance [overlap ok] FromPyObject CDouble instance [overlap ok] ToPyObject CDouble instance [overlap ok] FromPyObject Integer instance [overlap ok] ToPyObject Integer instance [overlap ok] FromPyObject CInt instance [overlap ok] ToPyObject CInt instance [overlap ok] FromPyObject CLong instance [overlap ok] ToPyObject CLong instance [overlap ok] FromPyObject String instance [overlap ok] ToPyObject String instance [overlap ok] ToPyObject CStringLen instance [overlap ok] (FromPyObject a, FromPyObject b) => FromPyObject [(a, b)] instance [overlap ok] (ToPyObject a, ToPyObject b) => ToPyObject [(a, b)] instance [overlap ok] FromPyObject a => FromPyObject [(a, PyObject)] instance [overlap ok] ToPyObject a => ToPyObject [(a, PyObject)] instance [overlap ok] FromPyObject [(PyObject, PyObject)] instance [overlap ok] ToPyObject [(PyObject, PyObject)] instance [overlap ok] FromPyObject [PyObject] instance [overlap ok] ToPyObject [PyObject] -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Interface to Python interpreter -- -- Written by John Goerzen, jgoerzen@complete.org module Python.Interpreter -- | Initialize the Python interpreter environment. -- -- MUST BE DONE BEFORE DOING ANYTHING ELSE! py_initialize :: IO () pyRun_SimpleString :: String -> IO () -- | Run some code in Python. pyRun_String :: String -> StartFrom -> [(String, PyObject)] -> IO PyObject -- | Like pyRun_String, but take more Haskellish args and results. pyRun_StringHs :: (ToPyObject b, FromPyObject c) => String -> StartFrom -> [(String, b)] -> IO c -- | How to interpret a snippet of Python code. data StartFrom Py_eval_input :: StartFrom Py_file_input :: StartFrom Py_single_input :: StartFrom -- | Call a function or callable object by name. callByName :: String -> [PyObject] -> [(String, PyObject)] -> IO PyObject -- | Call a function or callable object by namem using Haskell args and -- return values.. -- -- You can use noParms and noKwParms if you have no simple -- or keyword parameters to pass, respectively. callByNameHs :: (ToPyObject a, ToPyObject b, FromPyObject c) => String -> [a] -> [(String, b)] -> IO c noParms :: [String] noKwParms :: [(String, String)] -- | Import a module into the current environment in the normal sense -- (similar to "import" in Python). pyImport :: String -> IO () -- | Wrapper around C PyImport_ImportModule, which imports a module. -- -- You may want the higher-level pyImport instead. pyImport_ImportModule :: String -> IO PyObject -- | Wrapper around C PyImport_AddModule, which looks up an existing module pyImport_AddModule :: String -> IO PyObject -- | Gets the dict associated with a module. pyModule_GetDict :: PyObject -> IO PyObject py_initializeThreaded :: IO () cpy_GILEnsure :: IO (Ptr CPyGILState) cpy_GILRelease :: Ptr CPyGILState -> IO () withGIL :: IO a -> IO a -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Python low-level exception handling -- -- Written by John Goerzen, jgoerzen@complete.org module Python.Exceptions -- | The type of Python exceptions. data PyException -- | Execute the given IO action. -- -- If it raises a PyException, then execute the supplied handler -- and return its return value. Otherwise, process as normal. catchPy :: IO a -> (PyException -> IO a) -> IO a -- | Like catchPy, with the order of arguments reversed. handlePy :: (PyException -> IO a) -> IO a -> IO a -- | Useful as the first argument to catchJust, tryJust, or handleJust. -- Return Nothing if the given exception is not a PyException, or -- the exception otherwise. pyExceptions :: Exception -> Maybe PyException -- | Like catchPy, but catches only instances of the Python class given -- (see doesExceptionMatch). catchSpecificPy :: PyObject -> IO a -> (PyException -> IO a) -> IO a -- | When an exception is thrown, it is not immediately formatted. -- -- This call will format it. formatException :: PyException -> IO PyException -- | Returns true if the passed PyException matches the given Python -- exception class or one of its subclasses. Standard Python exception -- classes are given in ExcTypes. doesExceptionMatch :: PyException -> PyObject -> IO Bool -- | A handler for use in catchPy or handlePy. Grabs the -- Python exception, describes it, and raises the description in the IO -- monad with fail. exc2ioerror :: PyException -> IO a -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Python file-like objects -- -- Written by John Goerzen, jgoerzen@complete.org -- -- This module provides a Haskell interface to work with Python file-like -- objects. The Haskell interface is a System.IO.HVIO interface, -- which is similar in concept to the Python file-like object system. -- -- You can create such objects by using openPyFile from this -- module, or openGz or openBz2. -- -- Functions that you can use to operate on these objects are defined at -- System.IO.HVIO. module Python.Objects.File -- | The basic type for a Python file or file-like object. -- -- PyFiles are a member of System.IO.HVIO and can be used as any -- other Haskell HVFS object such as a Handle. -- -- PyFile objects cannot reliably detect EOF when asked by -- vIsEOF, but can detect it and raise the appropriate IOError -- when it is reached. Also, PyFile objects cannot determine if -- they are readable, writable, or seekable in advance. data PyFile -- | Takes a PyObject representing a Python file or file-like object -- and makes it into a PyFile. mkPyFile :: PyObject -> PyFile -- | Extracts the PyObject representing this PyFile. fromPyFile :: PyFile -> PyObject -- | Open a file on disk and return a PyFile. openPyFile :: FilePath -> IOMode -> IO PyFile -- | Wrap an operation, raising exceptions in the IO monad as appropriate. pyfwrap :: PyFile -> (PyObject -> IO a) -> IO a -- | Convert a Haskell open mode to a Python mode string openModeConv :: IOMode -> [Char] instance [overlap ok] HVIO PyFile instance [overlap ok] Show PyFile -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Python low-level exception definitions -- -- These are definitions of the built-in Python exception objects. You -- can use them with doesExceptionMatch and -- catchSpecificPy. -- -- The meanings of these exceptions can be found at -- http://www.python.org/doc/current/lib/module-exceptions.html. -- -- Please note that windowsError is available only on Microsoft -- platforms. -- -- Written by John Goerzen, jgoerzen@complete.org module Python.Exceptions.ExcTypes arithmeticError :: PyObject assertionError :: PyObject attributeError :: PyObject pyEOFError :: PyObject environmentError :: PyObject -- | This is Exception in Python; renamed to avoid naming conflicts here. pyMainException :: PyObject floatingPointError :: PyObject pyIOError :: PyObject importError :: PyObject indexError :: PyObject keyError :: PyObject keyboardInterrupt :: PyObject lookupError :: PyObject memoryError :: PyObject nameError :: PyObject notImplementedError :: PyObject pyOSError :: PyObject overflowError :: PyObject referenceError :: PyObject runtimeError :: PyObject standardError :: PyObject syntaxError :: PyObject systemError :: PyObject systemExit :: PyObject typeError :: PyObject valueError :: PyObject zeroDivisionError :: PyObject -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Python dict-like objects -- -- Written by John Goerzen, jgoerzen@complete.org -- -- This module can be used to access Python dicts and dict-like objects -- such as dbm databases. For a higher-level interface to creating and -- working with these dbm interfaces, please see the functions in -- MissingPy.AnyDBM. Also, for functions that use this, please see -- Database.AnyDBM. module Python.Objects.Dict -- | The basic type for a Python dict or dict-like object. data PyDict -- | Takes a PyObject representing a Python dict or dict-like objext -- and makes it into a PyDict. mkPyDict :: PyObject -> PyDict -- | Takes a PyDict and returns its internal PyObject. fromPyDict :: PyDict -> PyObject instance [overlap ok] AnyDBM PyDict -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- This module interfaces Database.AnyDBM to Python's anydbm.py. -- Implementations for specific Python *dbm modules are also available. -- -- See and import Database.AnyDBM to use these features. -- -- Written by John Goerzen, jgoerzen@complete.org module MissingPy.AnyDBM -- | Flags used to open a dbm-type database data PyDBMOpenFlags -- | Open an existing database for read only DBM_ReadOnly :: PyDBMOpenFlags -- | Open an existing database for reading and writing DBM_ReadWrite :: PyDBMOpenFlags -- | Open a database for reading and writing, creating if it doesn't exist DBM_ReadWriteCreate :: PyDBMOpenFlags -- | Open a database, creating it anew each time (deleting any existing -- data) DBM_ReadWriteNew :: PyDBMOpenFlags -- | Opens a persistent storage database using the "best" storage mechanism -- available to Python on this system. This will usually be one of the -- *dbm services, though in rare circumstances, could be "dumbdbm", which -- is only marginally better than Database.AnyDBM.StringDBM. openAnyDBM :: FilePath -> PyDBMOpenFlags -> IO PyDict -- | Open a database using a specific module given by the first parameter. -- The module supported are: -- -- -- -- SECURITY NOTE: the string is not validated before being passed to -- Python. Do not pass an arbitrary value to this function. openSpecificDBM :: String -> FilePath -> PyDBMOpenFlags -> IO PyDict -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Support for GZip files -- -- Written by John Goerzen, jgoerzen@complete.org module MissingPy.FileArchive.GZip -- | Open a GZip file. The compression level should be from 1 (least -- compression) to 9 (most compression). This is ignored when the file is -- opened read-only. -- -- Once opened, the functions defined in HVIO can be used to work -- with it. openGz :: FilePath -> IOMode -> Int -> IO PyFile -- | Maintainer : jgoerzen@complete.org Stability : provisional -- Portability: portable -- -- Support for BZip2 files -- -- Written by John Goerzen, jgoerzen@complete.org module MissingPy.FileArchive.BZip2 -- | Open a BZip2 file. The compression level should be from 1 (least -- compression) to 9 (most compression). This is ignored when the file is -- opened read-only. -- -- Once opened, the functions defined in System.IO.HVIO can be -- used to work with it. -- -- BZip2 supports only ReadMode and WriteMode for the IOMode. openBz2 :: FilePath -> IOMode -> Int -> IO PyFile