-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Python interpreter embedded into haskell.
--   
--   This package embeds python interpreter into haskell program and allows
--   to write python snippets as quasiquotes. Values could be easily
--   transferred between python and haskell. It's possible to call haskell
--   from python as well.
@package inline-python
@version 0.1


-- | Data types and utilities.
module Python.Inline.Types

-- | Monad for code which is interacts with python interpreter. Only one
--   haskell thread can interact with python interpreter at a time.
--   Function that execute <tt>Py</tt> make sure that this invariant is
--   held. Also note that all code in <tt>Py</tt> monad is executed with
--   asynchronous exception masked, but <a>liftIO</a> removes mask.
data Py a

-- | Execute python action. It will take and hold global lock while code is
--   executed. Python exceptions raised during execution are converted to
--   haskell exception <a>PyError</a>.
runPy :: Py a -> IO a

-- | Inject <tt>IO</tt> into <tt>Py</tt> monad without changing masking
--   state (unlike <a>liftIO</a>)
pyIO :: IO a -> Py a

-- | Some python object. Since almost everything in python is mutable it
--   could only be accessed only in IO monad.
data PyObject
unsafeWithPyObject :: forall a. PyObject -> (Ptr PyObject -> Py a) -> Py a

-- | Python exception converted to haskell.
data PyError

-- | Python exception. Contains exception type and message as strings.
PyError :: !PyException -> PyError

-- | It's not possible to convert given python value to a haskell value
BadPyType :: PyError

-- | Data type is suitable but value is outside of allowed range. For
--   example attempting to convert 1000 to <tt>Word8</tt> will result in
--   this exception.
OutOfRange :: PyError

-- | Initialization of python interpreter failed
PyInitializationFailed :: PyError

-- | Python interpreter is not initialized
PythonNotInitialized :: PyError

-- | Python interpreter is not initialized
PythonIsFinalized :: PyError

-- | Python exception converted to haskell value
data PyException
PyException :: !String -> !String -> !PyObject -> PyException

-- | Exception type as a string
[$sel:ty:PyException] :: PyException -> !String

-- | String representation of an exception
[$sel:str:PyException] :: PyException -> !String

-- | Exception object
[$sel:exception:PyException] :: PyException -> !PyObject

-- | Internal error. If this exception is thrown it means there's bug in a
--   library.
data PyInternalError
PyInternalError :: String -> PyInternalError


-- | Conversion between haskell data types and python values
module Python.Inline.Literal

-- | Convert python object to haskell value.
class FromPy a

-- | Convert python value into haskell value. This function should try to
--   not modify python's data. This function should avoid throwing haskell
--   exception. Any python exceptions should be thrown as <a>PyError</a>.
--   When data type couldn't be converted <a>BadPyType</a> or
--   <a>OutOfRange</a> should be thrown to indicate failure.
--   
--   This is low level function. It should be only used when working with
--   python's C API. Otherwise <a>fromPy</a> is preferred.
basicFromPy :: FromPy a => Ptr PyObject -> Py a

-- | Convert haskell value to python value.
class ToPy a

-- | Convert haskell value to python object. This function returns strong
--   reference to newly create objects (except singletons like
--   <tt>None</tt>, <tt>True</tt>, etc).
--   
--   Implementations should try to avoid failing conversions. There're two
--   ways of signalling failure: errors on python side should return NULL
--   and raise python exception. Haskell code should just throw exception.
--   
--   This is low level function. It should be only used when working with
--   python's C API. Otherwise <a>toPy</a> is preferred.
basicToPy :: ToPy a => a -> Py (Ptr PyObject)

-- | Old hack for handling of strings
basicListToPy :: ToPy a => [a] -> Py (Ptr PyObject)

-- | Convert haskell value to a python object.
toPy :: ToPy a => a -> Py PyObject

-- | Convert python object to haskell value. All python exceptions which
--   happen during execution will be converted to <tt>PyError</tt>.
fromPyEither :: FromPy a => PyObject -> Py (Either PyError a)

-- | Convert python object to haskell value. Will return <tt>Nothing</tt>
--   if <a>BadPyType</a> or <a>OutOfRange</a> is thrown. Other python
--   exceptions are rethrown.
fromPy :: FromPy a => PyObject -> Py (Maybe a)

-- | Convert python object to haskell value. Throws exception on failure.
fromPy' :: FromPy a => PyObject -> Py a
instance Python.Inline.Literal.ToPy GHC.Int.Int64
instance Python.Inline.Literal.FromPy GHC.Int.Int64
instance Python.Inline.Literal.ToPy GHC.Word.Word64
instance Python.Inline.Literal.FromPy GHC.Word.Word64
instance Python.Inline.Literal.ToPy Foreign.C.Types.CInt
instance Python.Inline.Literal.FromPy Foreign.C.Types.CInt
instance Python.Inline.Literal.ToPy Foreign.C.Types.CUInt
instance Python.Inline.Literal.FromPy Foreign.C.Types.CUInt
instance Python.Inline.Literal.ToPy Foreign.C.Types.CShort
instance Python.Inline.Literal.FromPy Foreign.C.Types.CShort
instance Python.Inline.Literal.ToPy Foreign.C.Types.CUShort
instance Python.Inline.Literal.FromPy Foreign.C.Types.CUShort
instance Python.Inline.Literal.ToPy Foreign.C.Types.CChar
instance Python.Inline.Literal.FromPy Foreign.C.Types.CChar
instance Python.Inline.Literal.ToPy Foreign.C.Types.CUChar
instance Python.Inline.Literal.FromPy Foreign.C.Types.CUChar
instance Python.Inline.Literal.ToPy Foreign.C.Types.CSChar
instance Python.Inline.Literal.FromPy Foreign.C.Types.CSChar
instance Python.Inline.Literal.ToPy GHC.Types.Double
instance Python.Inline.Literal.FromPy GHC.Types.Double
instance Python.Inline.Literal.FromPy Python.Internal.Types.PyObject
instance Python.Inline.Literal.FromPy Foreign.C.Types.CLong
instance Python.Inline.Literal.FromPy Foreign.C.Types.CLLong
instance Python.Inline.Literal.FromPy Foreign.C.Types.CULong
instance Python.Inline.Literal.FromPy Foreign.C.Types.CULLong
instance Python.Inline.Literal.FromPy Foreign.C.Types.CDouble
instance Python.Inline.Literal.FromPy GHC.Types.Float
instance Python.Inline.Literal.FromPy GHC.Types.Int
instance Python.Inline.Literal.FromPy GHC.Types.Word
instance Python.Inline.Literal.FromPy GHC.Int.Int8
instance Python.Inline.Literal.FromPy GHC.Int.Int16
instance Python.Inline.Literal.FromPy GHC.Int.Int32
instance Python.Inline.Literal.FromPy GHC.Word.Word8
instance Python.Inline.Literal.FromPy GHC.Word.Word16
instance Python.Inline.Literal.FromPy GHC.Word.Word32
instance Python.Inline.Literal.FromPy GHC.Types.Char
instance Python.Inline.Literal.FromPy GHC.Types.Bool
instance (Python.Inline.Literal.FromPy a, Python.Inline.Literal.FromPy b) => Python.Inline.Literal.FromPy (a, b)
instance (Python.Inline.Literal.FromPy a, Python.Inline.Literal.FromPy b, Python.Inline.Literal.FromPy c) => Python.Inline.Literal.FromPy (a, b, c)
instance (Python.Inline.Literal.FromPy a, Python.Inline.Literal.FromPy b, Python.Inline.Literal.FromPy c, Python.Inline.Literal.FromPy d) => Python.Inline.Literal.FromPy (a, b, c, d)
instance Python.Inline.Literal.FromPy a => Python.Inline.Literal.FromPy [a]
instance (Python.Inline.Literal.FromPy a, GHC.Classes.Ord a) => Python.Inline.Literal.FromPy (Data.Set.Internal.Set a)
instance (Python.Inline.Literal.FromPy k, Python.Inline.Literal.FromPy v, GHC.Classes.Ord k) => Python.Inline.Literal.FromPy (Data.Map.Internal.Map k v)
instance Python.Inline.Literal.FromPy a => Python.Inline.Literal.FromPy (Data.Vector.Vector a)
instance (Python.Inline.Literal.FromPy a, Foreign.Storable.Storable a) => Python.Inline.Literal.FromPy (Data.Vector.Storable.Vector a)
instance (Python.Inline.Literal.FromPy a, Data.Primitive.Types.Prim a) => Python.Inline.Literal.FromPy (Data.Vector.Primitive.Vector a)
instance (Python.Inline.Literal.FromPy a, Data.Vector.Unboxed.Base.Unbox a) => Python.Inline.Literal.FromPy (Data.Vector.Unboxed.Base.Vector a)
instance Python.Inline.Literal.FromPy a => Python.Inline.Literal.FromPy (Data.Vector.Strict.Vector a)
instance (Python.Inline.Literal.FromPy a, GHC.Show.Show a, Python.Inline.Literal.ToPy b) => Python.Inline.Literal.ToPy (a -> GHC.Types.IO b)
instance (Python.Inline.Literal.FromPy a1, Python.Inline.Literal.FromPy a2, Python.Inline.Literal.ToPy b) => Python.Inline.Literal.ToPy (a1 -> a2 -> GHC.Types.IO b)
instance Python.Inline.Literal.ToPy Python.Internal.Types.PyObject
instance Python.Inline.Literal.ToPy ()
instance Python.Inline.Literal.ToPy Foreign.C.Types.CLong
instance Python.Inline.Literal.ToPy Foreign.C.Types.CLLong
instance Python.Inline.Literal.ToPy Foreign.C.Types.CULong
instance Python.Inline.Literal.ToPy Foreign.C.Types.CULLong
instance Python.Inline.Literal.ToPy Foreign.C.Types.CDouble
instance Python.Inline.Literal.ToPy GHC.Types.Float
instance Python.Inline.Literal.ToPy GHC.Types.Int
instance Python.Inline.Literal.ToPy GHC.Types.Word
instance Python.Inline.Literal.ToPy GHC.Int.Int8
instance Python.Inline.Literal.ToPy GHC.Int.Int16
instance Python.Inline.Literal.ToPy GHC.Int.Int32
instance Python.Inline.Literal.ToPy GHC.Word.Word8
instance Python.Inline.Literal.ToPy GHC.Word.Word16
instance Python.Inline.Literal.ToPy GHC.Word.Word32
instance Python.Inline.Literal.ToPy GHC.Types.Char
instance Python.Inline.Literal.ToPy GHC.Types.Bool
instance (Python.Inline.Literal.ToPy a, Python.Inline.Literal.ToPy b) => Python.Inline.Literal.ToPy (a, b)
instance (Python.Inline.Literal.ToPy a, Python.Inline.Literal.ToPy b, Python.Inline.Literal.ToPy c) => Python.Inline.Literal.ToPy (a, b, c)
instance (Python.Inline.Literal.ToPy a, Python.Inline.Literal.ToPy b, Python.Inline.Literal.ToPy c, Python.Inline.Literal.ToPy d) => Python.Inline.Literal.ToPy (a, b, c, d)
instance Python.Inline.Literal.ToPy a => Python.Inline.Literal.ToPy [a]
instance (Python.Inline.Literal.ToPy a, GHC.Classes.Ord a) => Python.Inline.Literal.ToPy (Data.Set.Internal.Set a)
instance (Python.Inline.Literal.ToPy k, Python.Inline.Literal.ToPy v, GHC.Classes.Ord k) => Python.Inline.Literal.ToPy (Data.Map.Internal.Map k v)
instance Python.Inline.Literal.ToPy a => Python.Inline.Literal.ToPy (Data.Vector.Vector a)
instance (Python.Inline.Literal.ToPy a, Foreign.Storable.Storable a) => Python.Inline.Literal.ToPy (Data.Vector.Storable.Vector a)
instance (Python.Inline.Literal.ToPy a, Data.Primitive.Types.Prim a) => Python.Inline.Literal.ToPy (Data.Vector.Primitive.Vector a)
instance (Python.Inline.Literal.ToPy a, Data.Vector.Unboxed.Base.Unbox a) => Python.Inline.Literal.ToPy (Data.Vector.Unboxed.Base.Vector a)
instance Python.Inline.Literal.ToPy a => Python.Inline.Literal.ToPy (Data.Vector.Strict.Vector a)
instance Python.Inline.Literal.ToPy b => Python.Inline.Literal.ToPy (GHC.Types.IO b)


-- | Quasiquoters for embedding python expression into haskell programs.
--   Python is statement oriented and heavily relies on mutable state. This
--   means we need several different quasiquoters.
--   
--   <h2>Syntax in quasiquotes</h2>
--   
--   Note on syntax. Python's grammar is indentation sensitive and
--   quasiquote is passed to <a>QuasiQuoter</a> without any adjustment. So
--   this seemingly reasonable code:
--   
--   <pre>
--   foo = [py_| do_this()
--               do_that()
--             |]
--   </pre>
--   
--   results in following source code.
--   
--   <pre>
--   do_this()
--              do_that()
--   </pre>
--   
--   There's no sensible way to adjust indentation, since we don't know
--   original indentation of first line of quasiquote in haskell's code.
--   Thus rule: <b>First line of multiline quasiquote must be empty</b>.
--   This is correct way to write code:
--   
--   <pre>
--   foo = [py_|
--           do_this()
--           do_that()
--           |]
--   </pre>
module Python.Inline.QQ

-- | Evaluate sequence of python statements. It works in the same way as
--   python's <tt>exec</tt>. All module imports and all variables defined
--   in this quasiquote will be visible to later quotes.
--   
--   It creates value of type <tt>Py ()</tt>
pymain :: QuasiQuoter

-- | Evaluate sequence of python statements. All module imports and all
--   variables defined in this quasiquote will be discarded and won't be
--   visible in later quotes.
--   
--   It creates value of type <tt>Py ()</tt>
py_ :: QuasiQuoter

-- | Evaluate single python expression. It only accepts single expressions
--   same as python's <tt>eval</tt>.
--   
--   This quote creates object of type <tt>Py PyObject</tt>
pye :: QuasiQuoter

-- | Another quasiquoter which works around that sequence of python
--   statements doesn't have any value associated with it. Content of
--   quasiquote is function body. So to get value out of it one must call
--   return
pyf :: QuasiQuoter


-- | This library allows to embed as quasiquotes and execute arbitrary
--   python code in haskell programs. Take for example following program:
--   
--   <pre>
--   {-# LANGUAGE QuasiQuotes #-}
--   import Python.Inline
--   import Python.Inline.QQ
--   
--   main :: IO ()
--   main = withPython $ do
--     let input = [1..10] :: [Int]
--     let square :: Int -&gt; Py Int
--         square x = pure (x * x)
--     print =&lt;&lt; runPy $ do
--       fromPy' @[Int] =&lt;&lt; [pye| [ square_hs(x) for x in input_hs ] |]
--   </pre>
--   
--   Quasiquotation <a>pye</a> captures variables <tt>input</tt> and
--   <tt>square</tt> from environment and produces python object which
--   <a>fromPy'</a> converts to haskell list. As one expect it would
--   output:
--   
--   <pre>
--   [1,4,9,16,25,36,49,64,81,100]
--   </pre>
--   
--   Module <a>Python.Inline.QQ</a> provides several quasiquoters with
--   different semantics but general rules are:
--   
--   <ol>
--   <li>All python variables ending with <tt>_hs</tt> are captured from
--   environment and converted to python objects according to their
--   <a>ToPy</a> instance.</li>
--   <li>Syntax errors in embedded python will be caught during
--   compilation.</li>
--   <li>All code interacting with python must be in <a>Py</a> monad which
--   could be run using <a>runPy</a>.</li>
--   <li>Python interpreter must be initialized before calling any python
--   code.</li>
--   </ol>
module Python.Inline

-- | Initialize python interpreter. If interpreter is already initialized
--   it's a noop. Calling after python was shut down will result in error.
initializePython :: IO ()

-- | Destroy python interpreter.
finalizePython :: IO ()

-- | Bracket which ensures that action is executed with properly
--   initialized interpreter
withPython :: IO a -> IO a

-- | Monad for code which is interacts with python interpreter. Only one
--   haskell thread can interact with python interpreter at a time.
--   Function that execute <tt>Py</tt> make sure that this invariant is
--   held. Also note that all code in <tt>Py</tt> monad is executed with
--   asynchronous exception masked, but <a>liftIO</a> removes mask.
data Py a

-- | Execute python action. It will take and hold global lock while code is
--   executed. Python exceptions raised during execution are converted to
--   haskell exception <a>PyError</a>.
runPy :: Py a -> IO a

-- | Same as <a>runPy</a> but will make sure that code is run in python's
--   main thread. It's thread in which python's interpreter was
--   initialized. Some python's libraries may need that. It has higher call
--   overhead compared to <a>runPy</a>.
runPyInMain :: Py a -> IO a

-- | Some python object. Since almost everything in python is mutable it
--   could only be accessed only in IO monad.
data PyObject

-- | Python exception converted to haskell.
data PyError

-- | Python exception. Contains exception type and message as strings.
PyError :: !PyException -> PyError

-- | It's not possible to convert given python value to a haskell value
BadPyType :: PyError

-- | Data type is suitable but value is outside of allowed range. For
--   example attempting to convert 1000 to <tt>Word8</tt> will result in
--   this exception.
OutOfRange :: PyError

-- | Initialization of python interpreter failed
PyInitializationFailed :: PyError

-- | Python interpreter is not initialized
PythonNotInitialized :: PyError

-- | Python interpreter is not initialized
PythonIsFinalized :: PyError

-- | Python exception converted to haskell value
data PyException
PyException :: !String -> !String -> !PyObject -> PyException

-- | Exception type as a string
[$sel:ty:PyException] :: PyException -> !String

-- | String representation of an exception
[$sel:str:PyException] :: PyException -> !String

-- | Exception object
[$sel:exception:PyException] :: PyException -> !PyObject

-- | Convert haskell value to a python object.
toPy :: ToPy a => a -> Py PyObject

-- | Convert python object to haskell value. All python exceptions which
--   happen during execution will be converted to <tt>PyError</tt>.
fromPyEither :: FromPy a => PyObject -> Py (Either PyError a)

-- | Convert python object to haskell value. Will return <tt>Nothing</tt>
--   if <a>BadPyType</a> or <a>OutOfRange</a> is thrown. Other python
--   exceptions are rethrown.
fromPy :: FromPy a => PyObject -> Py (Maybe a)

-- | Convert python object to haskell value. Throws exception on failure.
fromPy' :: FromPy a => PyObject -> Py a

-- | Convert haskell value to python value.
class ToPy a

-- | Convert python object to haskell value.
class FromPy a