This is Python.info, produced by Macaulay2, version 1.25.05

Python -- interface to Python
*****************************

Description
===========

This package provides a basic interface to run Python code within Macaulay2 and
to convert back and forth between Python and Macaulay2 objects.

+--------------------------------------------------------------------+
|i1 : toPython {1, 2/3, "foo", (1, 2, 3), hashTable {"foo" => "bar"}}|
|                                                                    |
|o1 = [1, 0.6666666666666666, 'foo', (1, 2, 3), {'foo': 'bar'}]      |
|                                                                    |
|o1 : PythonObject of class list                                     |
+--------------------------------------------------------------------+
|i2 : value pythonValue "[1, 2/3, 'foo', (1, 2, 3), {'foo' : 'bar'}]"|
|                                                                    |
|o2 = {1, .666667, foo, (1, 2, 3), HashTable{"foo" => bar}}          |
|                                                                    |
|o2 : List                                                           |
+--------------------------------------------------------------------+
|i3 : math = import "math"                                           |
|                                                                    |
|o3 = <module 'math' (built-in)>                                     |
|                                                                    |
|o3 : PythonObject of class module                                   |
+--------------------------------------------------------------------+
|i4 : math@@sqrt 2                                                   |
|                                                                    |
|o4 = 1.4142135623730951                                             |
|                                                                    |
|o4 : PythonObject of class float                                    |
+--------------------------------------------------------------------+

Authors
=======

  * Daniel R. Grayson (see https://faculty.math.illinois.edu/~dan/ )
    <danielrichardgrayson@gmail.com>
  * Doug Torrance (see https://webwork.piedmont.edu/~dtorrance )
    <dtorrance@piedmont.edu>

Version
=======

This documentation describes version 0.6 of Python.

Citation
========

If you have used this package in your research, please cite it as follows:

+----------------------------------------------------------------------------+
|@misc{PythonSource,                                                         |
|  title = {{Python: interface to Python. Version~0.6}},                     |
|  author = {Daniel R. Grayson and Doug Torrance},                           |
|  howpublished = {A \emph{Macaulay2} package available at                   |
|    \url{https://github.com/Macaulay2/M2/tree/master/M2/Macaulay2/packages}}|
|}                                                                           |
|                                                                            |
+----------------------------------------------------------------------------+

Exports
=======

  * Types
      * PythonObject -- a python object
  * Functions and commands
      * addPyToM2Function -- convenience function for
        adding value hooks
      * context (missing documentation)
      * getattr -- get an attribute of a python object
      * getitem -- get elements of python sequences
      * hasattr -- whether a python object has an attribute
      * import -- import a Python module
      * objectType -- type of a python object
      * pythonHelp (missing documentation)
      * pythonValue -- execute Python source code from a
        string
      * runSimpleString -- execute Python source code
        from a string in __main__
      * setattr -- set an attribute of a python object
      * setitem -- set elements of mutable python sequences
      * toFunction -- convert callable python objects to
        Macaulay2 functions
      * toPython -- convert Macaulay2 things to Python objects
  * Methods
      * ?? PythonObject (missing documentation)
      * abs(PythonObject) -- absolute value of a
        python object
      * "addPyToM2Function(List,Function,String)" -- see
        addPyToM2Function, -- convenience function for
        adding value hooks
      * "addPyToM2Function(String,Function,String)" -- see
        addPyToM2Function, -- convenience function for
        adding value hooks
      * ceiling(PythonObject) -- ceiling of a
        python object
      * context(String) (missing documentation)
      * describe(PythonObject) (missing documentation)
      * expression(PythonObject) (missing documentation)
      * floor(PythonObject) -- floor of a
        python object
      * "getattr(PythonObject,String)" -- see getattr, -- get an
        attribute of a python object
      * "PythonObject @@ Thing" -- see getattr, -- get an
        attribute of a python object
      * "getitem(PythonObject,Thing)" -- see getitem, -- get
        elements of python sequences
      * "PythonObject _ Thing" -- see getitem, -- get elements
        of python sequences
      * "hasattr(PythonObject,String)" -- see hasattr, --
        whether a python object has an attribute
      * help(PythonObject) -- documentation for
        python object
      * "import(String)" -- see import, -- import a Python module
      * "isMember(PythonObject,PythonObject)" -- see
        isMember(Thing,PythonObject), --
        test membership in a python object
      * isMember(Thing,PythonObject),
        -- test membership in a python object
      * iterator(PythonObject) -- get
        iterator of iterable python object
      * length(PythonObject) -- returns the
        length of a python object
      * net(PythonObject) (missing documentation)
      * next(PythonObject) -- retrieve the next
        item from a python iterator
      * "+ PythonObject" -- see PythonObject, -- a python
        object
      * "- PythonObject" -- see PythonObject, -- a python
        object
      * "PythonObject % PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject % Thing" -- see PythonObject, -- a
        python object
      * "PythonObject & PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject & Thing" -- see PythonObject, -- a
        python object
      * "PythonObject * PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject * Thing" -- see PythonObject, -- a
        python object
      * "PythonObject + PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject + Thing" -- see PythonObject, -- a
        python object
      * "PythonObject - PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject - Thing" -- see PythonObject, -- a
        python object
      * "PythonObject / PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject / Thing" -- see PythonObject, -- a
        python object
      * "PythonObject // PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject // Thing" -- see PythonObject, -- a
        python object
      * "PythonObject << PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject << Thing" -- see PythonObject, -- a
        python object
      * "PythonObject == PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject == Thing" -- see PythonObject, -- a
        python object
      * "PythonObject >> PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject >> Thing" -- see PythonObject, -- a
        python object
      * "PythonObject ? PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject ? Thing" -- see PythonObject, -- a
        python object
      * "PythonObject @ PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject @ Thing" -- see PythonObject, -- a
        python object
      * "PythonObject ^ PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject ^ Thing" -- see PythonObject, -- a
        python object
      * "PythonObject ^^ PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject ^^ Thing" -- see PythonObject, -- a
        python object
      * "PythonObject | PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject | Thing" -- see PythonObject, -- a
        python object
      * "PythonObject and PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject and Thing" -- see PythonObject, -- a
        python object
      * "PythonObject or PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject or Thing" -- see PythonObject, -- a
        python object
      * "PythonObject xor PythonObject" -- see PythonObject,
        -- a python object
      * "PythonObject xor Thing" -- see PythonObject, -- a
        python object
      * "Thing % PythonObject" -- see PythonObject, -- a
        python object
      * "Thing & PythonObject" -- see PythonObject, -- a
        python object
      * "Thing * PythonObject" -- see PythonObject, -- a
        python object
      * "Thing + PythonObject" -- see PythonObject, -- a
        python object
      * "Thing - PythonObject" -- see PythonObject, -- a
        python object
      * "Thing / PythonObject" -- see PythonObject, -- a
        python object
      * "Thing // PythonObject" -- see PythonObject, -- a
        python object
      * "Thing << PythonObject" -- see PythonObject, -- a
        python object
      * "Thing == PythonObject" -- see PythonObject, -- a
        python object
      * "Thing >> PythonObject" -- see PythonObject, -- a
        python object
      * "Thing ? PythonObject" -- see PythonObject, -- a
        python object
      * "Thing @ PythonObject" -- see PythonObject, -- a
        python object
      * "Thing ^ PythonObject" -- see PythonObject, -- a
        python object
      * "Thing ^^ PythonObject" -- see PythonObject, -- a
        python object
      * "Thing | PythonObject" -- see PythonObject, -- a
        python object
      * "Thing and PythonObject" -- see PythonObject, -- a
        python object
      * "Thing or PythonObject" -- see PythonObject, -- a
        python object
      * "Thing xor PythonObject" -- see PythonObject, -- a
        python object
      * PythonObject %= Thing (missing documentation)
      * PythonObject &= Thing (missing documentation)
      * PythonObject *= Thing (missing documentation)
      * PythonObject += Thing (missing documentation)
      * PythonObject -= Thing (missing documentation)
      * PythonObject //= Thing (missing documentation)
      * PythonObject /= Thing (missing documentation)
      * PythonObject <<= Thing (missing documentation)
      * PythonObject >>= Thing (missing documentation)
      * PythonObject @= Thing (missing documentation)
      * PythonObject ^= Thing (missing documentation)
      * PythonObject ^^= Thing (missing documentation)
      * PythonObject |= Thing (missing documentation)
      * PythonObject ~ -- bitwise not of a python object
      * "pythonValue(Sequence)" -- see pythonValue, --
        execute Python source code from a string
      * "pythonValue(String)" -- see pythonValue, -- execute
        Python source code from a string
      * quotientRemainder(PythonObject,PythonObject)
        -- quotient and
        remainder of python objects
      * "quotientRemainder(PythonObject,Thing)" -- see
        quotientRemainder(PythonObject,PythonObject),
        -- quotient and
        remainder of python objects
      * "quotientRemainder(Thing,PythonObject)" -- see
        quotientRemainder(PythonObject,PythonObject),
        -- quotient and
        remainder of python objects
      * "round(PythonObject)" -- see round(ZZ,PythonObject),
        -- round a python object
      * "round(PythonObject,PythonObject)" -- see round(ZZ,PythonObject),
        -- round a python object
      * round(ZZ,PythonObject) -- round a
        python object
      * "PythonObject @@ Thing = Thing" -- see setattr, -- set
        an attribute of a python object
      * "setattr(PythonObject,String,Thing)" -- see setattr, --
        set an attribute of a python object
      * "PythonObject _ Thing = Thing" -- see setitem, -- set
        elements of mutable python sequences
      * "setitem(PythonObject,Thing,Thing)" -- see setitem, --
        set elements of mutable python sequences
      * texMath(PythonObject) (missing documentation)
      * toExternalString(PythonObject) (missing documentation)
      * "PythonObject Thing" -- see toFunction, -- convert
        callable python objects to Macaulay2 functions
      * "toFunction(PythonObject)" -- see toFunction, --
        convert callable python objects to Macaulay2 functions
      * "toPython(Boolean)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(CC)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(Constant)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(Function)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(HashTable)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(Nothing)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(PythonObject)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(QQ)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(RR)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(Sequence)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(Set)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * "toPython(String)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(VisibleList)" -- see toPython, -- convert
        Macaulay2 things to Python objects
      * "toPython(ZZ)" -- see toPython, -- convert Macaulay2
        things to Python objects
      * toString(PythonObject) (missing documentation)
      * truncate(PythonObject) -- truncate a
        python object
      * value(PythonObject) -- convert python
        objects to Macaulay2 things
  * Symbols
      * dict (missing documentation)
      * eval (missing documentation)
      * expr (missing documentation)
      * Preprocessor (missing documentation)
      * stmt (missing documentation)
      * stmtexpr (missing documentation)
      * symbols (missing documentation)
      * val (missing documentation)
      * valuestring (missing documentation)
  * Mutable symbols
      * dict (missing documentation)
      * eval (missing documentation)
      * expr (missing documentation)
      * stmt (missing documentation)
      * stmtexpr (missing documentation)
      * symbols (missing documentation)
      * val (missing documentation)
      * valuestring (missing documentation)

For the programmer
==================

The object Python, is a package (Macaulay2Doc),
defined in Python.m2, with auxiliary files in Python/.

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:19:0.

abs(PythonObject) -- absolute value of a python object
******************************************************

  * Function: abs (Macaulay2Doc),
  * Usage:
        abs x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the absolute value of x;

Description
===========

This is equivalent to the Python abs (see
https://docs.python.org/3/library/functions.html#abs ) function.

+------------------------------+
|i1 : abs toPython(-12)        |
|                              |
|o1 = 12                       |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * abs(PythonObject) -- absolute value of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:352:0.

addPyToM2Function -- convenience function for adding value hooks
****************************************************************

  * Usage:
        addPyToM2Function(type, f, desc)
  * Inputs:
      * type, a string (Macaulay2Doc), or a list (Macaulay2Doc),
        the type(s) to convert;
      * f, a function (Macaulay2Doc), the function that will do
        the converting;
      * desc, a string (Macaulay2Doc), passed to the Strategy
        option of addHook (Macaulay2Doc),;

Description
===========

Most of the hooks used by value (Macaulay2Doc), have the same
general format: if the python object has a particular type, then use a
particular function to convert it to a corresponding Macaulay2 thing.  This
function simplifies the process of adding such a hook.

For example, suppose we would like to convert Fraction objects from the Python
fractions (see https://docs.python.org/3/library/fractions.html ) module to
QQ (Macaulay2Doc), objects.  Without adding a hook, see value (Macaulay2Doc),
will do nothing with these objects.

+-----------------------------------------------------------------+
|i1 : fractions = import "fractions"                              |
|                                                                 |
|o1 = <module 'fractions' from '/usr/lib/python3.12/fractions.py'>|
|                                                                 |
|o1 : PythonObject of class module                                |
+-----------------------------------------------------------------+
|i2 : x = fractions@@"Fraction"(2, 3)                             |
|                                                                 |
|o2 = 2/3                                                         |
|                                                                 |
|o2 : PythonObject of class fractions.Fraction                    |
+-----------------------------------------------------------------+
|i3 : value x                                                     |
|                                                                 |
|o3 = 2/3                                                         |
|                                                                 |
|o3 : PythonObject of class fractions.Fraction                    |
+-----------------------------------------------------------------+

So we write a function to do the conversion and then install the hook using
addPyToM2Function.

+--------------------------------------------------------------------------+
|i4 : toQQ = x -> value x@@"numerator" / value x@@"denominator";           |
+--------------------------------------------------------------------------+
|i5 : addPyToM2Function("Fraction", toQQ, "Fraction -> QQ");               |
+--------------------------------------------------------------------------+
|i6 : value x                                                              |
|                                                                          |
|     2                                                                    |
|o6 = -                                                                    |
|     3                                                                    |
|                                                                          |
|o6 : QQ                                                                   |
+--------------------------------------------------------------------------+
|i7 : hooks value                                                          |
|                                                                          |
|o7 = {0 => (value, PythonObject, Strategy => unknown -> PythonObject)    }|
|     {1 => (value, PythonObject, Strategy => function -> FunctionClosure)}|
|     {2 => (value, PythonObject, Strategy => Counter -> Tally)           }|
|     {3 => (value, PythonObject, Strategy => dict -> HashTable)          }|
|     {4 => (value, PythonObject, Strategy => set -> Set)                 }|
|     {5 => (value, PythonObject, Strategy => list -> List)               }|
|     {6 => (value, PythonObject, Strategy => tuple -> Sequence)          }|
|     {7 => (value, PythonObject, Strategy => str -> String)              }|
|     {8 => (value, PythonObject, Strategy => complex -> CC)              }|
|     {9 => (value, PythonObject, Strategy => float -> RR)                }|
|     {10 => (value, PythonObject, Strategy => int -> ZZ)                 }|
|     {11 => (value, PythonObject, Strategy => bool -> Boolean)           }|
|     {12 => (value, PythonObject, Strategy => Fraction -> QQ)            }|
|                                                                          |
|o7 : NumberedVerticalList                                                 |
+--------------------------------------------------------------------------+

Ways to use addPyToM2Function:
==============================

  * "addPyToM2Function(List,Function,String)"
  * "addPyToM2Function(String,Function,String)"

For the programmer
==================

The object addPyToM2Function, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:463:0.

ceiling(PythonObject) -- ceiling of a python object
***************************************************

  * Function: ceiling (Macaulay2Doc),
  * Usage:
        ceiling x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.ceil function, which rounds toward positive
infinity.

+------------------------------+
|i1 : ceiling toPython 5.8     |
|                              |
|o1 = 6                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : ceiling toPython(-5.8)   |
|                              |
|o2 = -5                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * ceiling(PythonObject) -- ceiling of a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:791:0.

context
*******

Ways to use context:
====================

  * context(String) (missing documentation)

For the programmer
==================

The object context (missing documentation) is a method function with options (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

dict
****

For the programmer
==================

The object dict (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

eval
****

For the programmer
==================

The object eval (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

expr
****

For the programmer
==================

The object expr (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

floor(PythonObject) -- floor of a python object
***********************************************

  * Function: floor (Macaulay2Doc),
  * Usage:
        floor x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.floor function, which rounds toward negative
infinity.

+------------------------------+
|i1 : floor toPython 5.8       |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : floor toPython(-5.8)     |
|                              |
|o2 = -6                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * floor(PythonObject) -- floor of a python
    object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:771:0.

getattr -- get an attribute of a python object
**********************************************

  * Usage:
        getattr(x, y)
        x@@y
  * Inputs:
      * x, a python object,
      * y, a string (Macaulay2Doc),
  * Outputs:
      * a python object,

Description
===========

This is equivalent to the Python getattr (see
https://docs.python.org/3/library/functions.html#getattr ) function.

+----------------------------------------+
|i1 : foo = pythonValue "'Hello, world!'"|
|                                        |
|o1 = Hello, world!                      |
|                                        |
|o1 : PythonObject of class str          |
+----------------------------------------+
|i2 : (getattr(foo, "upper"))()          |
|                                        |
|o2 = HELLO, WORLD!                      |
|                                        |
|o2 : PythonObject of class str          |
+----------------------------------------+

In Python, "." is generally used as a shortcut for this function, but it is not
easily overloadable in Macaulay2.  Instead, @@ may be used for this purpose, as
its precedence is similar to "."  In this case, y  need not be a string.

+------------------------------+
|i3 : foo@@lower()             |
|                              |
|o3 = hello, world!            |
|                              |
|o3 : PythonObject of class str|
+------------------------------+

Ways to use getattr:
====================

  * "getattr(PythonObject,String)"

For the programmer
==================

The object getattr, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:568:0.

getitem -- get elements of python sequences
*******************************************

  * Usage:
        getitem(x, y)
        x_y
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
  * Outputs:
      * a python object,

Description
===========

You may access elements of python sequences using getitem or the shortcut _.
This is equivalent to square brackets ([]) in Python. For example, this works
for lists.

+--------------------------------+
|i1 : x = pythonValue "[1,2,3,4]"|
|                                |
|o1 = [1, 2, 3, 4]               |
|                                |
|o1 : PythonObject of class list |
+--------------------------------+
|i2 : getitem(x, 0)              |
|                                |
|o2 = 1                          |
|                                |
|o2 : PythonObject of class int  |
+--------------------------------+
|i3 : x_1                        |
|                                |
|o3 = 2                          |
|                                |
|o3 : PythonObject of class int  |
+--------------------------------+

It also works for dictionaries.

+------------------------------------------+
|i4 : x = pythonValue "{'spam':1,'eggs':2}"|
|                                          |
|o4 = {'spam': 1, 'eggs': 2}               |
|                                          |
|o4 : PythonObject of class dict           |
+------------------------------------------+
|i5 : getitem(x, "spam")                   |
|                                          |
|o5 = 1                                    |
|                                          |
|o5 : PythonObject of class int            |
+------------------------------------------+
|i6 : x_"eggs"                             |
|                                          |
|o6 = 2                                    |
|                                          |
|o6 : PythonObject of class int            |
+------------------------------------------+

Ways to use getitem:
====================

  * "getitem(PythonObject,Thing)"

For the programmer
==================

The object getitem, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:162:0.

hasattr -- whether a python object has an attribute
***************************************************

  * Usage:
        hasattr(x, y)
  * Inputs:
      * x, a python object,
      * y, a string (Macaulay2Doc),
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether y is an
        attribute of x;

Description
===========

This is equivalent to the Python hasattr (see
https://docs.python.org/3/library/functions.html#hasattr ) function.

+----------------------------------------+
|i1 : foo = pythonValue "'Hello, world!'"|
|                                        |
|o1 = Hello, world!                      |
|                                        |
|o1 : PythonObject of class str          |
+----------------------------------------+
|i2 : hasattr(foo, "upper")              |
|                                        |
|o2 = true                               |
+----------------------------------------+
|i3 : hasattr(foo, "bar")                |
|                                        |
|o3 = false                              |
+----------------------------------------+

Ways to use hasattr:
====================

  * "hasattr(PythonObject,String)"

For the programmer
==================

The object hasattr, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:592:0.

help(PythonObject) -- documentation for python object
*****************************************************

  * Function: help (Macaulay2Doc),
  * Usage:
        help x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a string (Macaulay2Doc),

Description
===========

This calls Python's built-in help function, which provides documentation for
Python objects.

+--------------------------------------------------------------+
|i1 : math = import "math"                                     |
|                                                              |
|o1 = <module 'math' (built-in)>                               |
|                                                              |
|o1 : PythonObject of class module                             |
+--------------------------------------------------------------+
|i2 : help math                                                |
|                                                              |
|o2 = This module provides access to the mathematical functions|
|     defined by the C standard.                               |
+--------------------------------------------------------------+
|i3 : help math@@sin                                           |
|                                                              |
|o3 = Return the sine of x (measured in radians).              |
+--------------------------------------------------------------+

Ways to use this method:
========================

  * help(PythonObject) -- documentation for
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:812:0.

import -- import a Python module
********************************

  * Usage:
        import s
  * Inputs:
      * s, a string (Macaulay2Doc), the name of a python module;
  * Outputs:
      * a python object, the imported module;

Description
===========

This is a wrapper around the Python C API function PyImport_ImportModule (see
https://docs.python.org/3/c-api/import.html#c.PyImport_ImportModule ) and
returns an imported Python module.

Once imported, the statements and definitions from the module are available
using getattr.

+---------------------------------+
|i1 : math = import "math"        |
|                                 |
|o1 = <module 'math' (built-in)>  |
|                                 |
|o1 : PythonObject of class module|
+---------------------------------+
|i2 : getattr(math, "pi")         |
|                                 |
|o2 = 3.141592653589793           |
|                                 |
|o2 : PythonObject of class float |
+---------------------------------+
|i3 : math@@sqrt 2                |
|                                 |
|o3 = 1.4142135623730951          |
|                                 |
|o3 : PythonObject of class float |
+---------------------------------+

Ways to use import:
===================

  * "import(String)"

For the programmer
==================

The object import, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:536:0.

isMember(Thing,PythonObject) -- test membership in a python object
******************************************************************

  * Function: isMember (Macaulay2Doc),
  * Usage:
        isMember(e, x)
  * Inputs:
      * e, a thing (Macaulay2Doc),
      * x, a python object,
  * Outputs:
      * a Boolean value (Macaulay2Doc), whether e is in x;

Description
===========

This calls Python's __contains__ method, which is equivalent to using the
Python in keyword.

+---------------------------------------------+
|i1 : isMember(toPython 3, toPython {1, 2, 3})|
|                                             |
|o1 = true                                    |
+---------------------------------------------+
|i2 : isMember(toPython 4, toPython {1, 2, 3})|
|                                             |
|o2 = false                                   |
+---------------------------------------------+

Note that testing a non-Python object for membership will always return false.

+------------------------------------+
|i3 : isMember(3, toPython {1, 2, 3})|
|                                    |
|o3 = false                          |
+------------------------------------+

Ways to use this method:
========================

  * "isMember(PythonObject,PythonObject)"
  * isMember(Thing,PythonObject), --
    test membership in a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:672:0.

iterator(PythonObject) -- get iterator of iterable python object
****************************************************************

  * Function: iterator (Macaulay2Doc),
  * Usage:
        i = iterator x
  * Inputs:
      * x, a python object, an iterable;
  * Outputs:
      * i, a python object, an iterator;

Description
===========

This function works just like its Python counterpart (see
https://docs.python.org/3/library/functions.html#iter ).  In particular, i is
an iterator for the iterable object x.

+----------------------------------------------+
|i1 : x = pythonValue "range(3)"               |
|                                              |
|o1 = range(0, 3)                              |
|                                              |
|o1 : PythonObject of class range              |
+----------------------------------------------+
|i2 : i = iterator x                           |
|                                              |
|o2 = <range_iterator object at 0x7f301b302490>|
|                                              |
|o2 : PythonObject of class range_iterator     |
+----------------------------------------------+

See also
========

  * next(PythonObject) -- retrieve the next item
    from a python iterator

Ways to use this method:
========================

  * iterator(PythonObject) -- get iterator
    of iterable python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:271:0.

length(PythonObject) -- returns the length of a python object
*************************************************************

  * Function: length (Macaulay2Doc),
  * Usage:
        length x
  * Inputs:
      * x, a python object,
  * Outputs:
      * an integer (Macaulay2Doc),

Description
===========

This is equivalent the Python len (see
https://docs.python.org/3/library/functions.html#len ) function.

+-----------------------------------------+
|i1 : length pythonValue "'Hello, world!'"|
|                                         |
|o1 = 13                                  |
+-----------------------------------------+
|i2 : length pythonValue "[1,2,3,4,5]"    |
|                                         |
|o2 = 5                                   |
+-----------------------------------------+

Ways to use this method:
========================

  * length(PythonObject) -- returns the length
    of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:390:0.

next(PythonObject) -- retrieve the next item from a python iterator
*******************************************************************

  * Function: next (Macaulay2Doc),
  * Usage:
        next i
  * Inputs:
      * i, a python object, an iterator;

Description
===========

This function works just like its Python counterpart (see
https://docs.python.org/3/library/functions.html#next ).  In particular, it
retrieves the next item from an iterator.

+----------------------------------------------+
|i1 : x = pythonValue "range(3)"               |
|                                              |
|o1 = range(0, 3)                              |
|                                              |
|o1 : PythonObject of class range              |
+----------------------------------------------+
|i2 : i = iterator x                           |
|                                              |
|o2 = <range_iterator object at 0x7efc56f8a490>|
|                                              |
|o2 : PythonObject of class range_iterator     |
+----------------------------------------------+
|i3 : next i                                   |
|                                              |
|o3 = 0                                        |
|                                              |
|o3 : PythonObject of class int                |
+----------------------------------------------+
|i4 : next i                                   |
|                                              |
|o4 = 1                                        |
|                                              |
|o4 : PythonObject of class int                |
+----------------------------------------------+
|i5 : next i                                   |
|                                              |
|o5 = 2                                        |
|                                              |
|o5 : PythonObject of class int                |
+----------------------------------------------+

When the iterator is exhausted, see StopIteration (Macaulay2Doc),
is returned.

+------------------+
|i6 : next i       |
|                  |
|o6 = StopIteration|
|                  |
|o6 : Symbol       |
+------------------+

See also
========

  * iterator(PythonObject) -- get iterator
    of iterable python object

Ways to use this method:
========================

  * next(PythonObject) -- retrieve the next item
    from a python iterator
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:300:0.

objectType -- type of a python object
*************************************

  * Usage:
        objectType x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the type of x;

Description
===========

This is equivalent to the type (see
https://docs.python.org/3/library/functions.html#type ) function in Python.

+---------------------------------------------+
|i1 : objectType pythonValue "2"              |
|                                             |
|o1 = <class 'int'>                           |
|                                             |
|o1 : PythonObject of class type              |
+---------------------------------------------+
|i2 : objectType pythonValue "'Hello, world!'"|
|                                             |
|o2 = <class 'str'>                           |
|                                             |
|o2 : PythonObject of class type              |
+---------------------------------------------+

For the programmer
==================

The object objectType, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:645:0.

Preprocessor
************

Functions with optional argument named Preprocessor:
====================================================

  * context(...,Preprocessor=>...) (missing documentation)

For the programmer
==================

The object Preprocessor (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

pythonHelp
**********

For the programmer
==================

The object pythonHelp (missing documentation) is a command (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

PythonObject -- a python object
*******************************

Description
===========

This type corresponds to all objects of the PyObject (see
https://docs.python.org/3/c-api/structures.html#c.PyObject ) type in the Python
C API, and in particular all of the types that users are familiar with from the
Python language itself.

You can perform basic arithmetic on python objects.

+--------------------------------+
|i1 : x = pythonValue "5"        |
|                                |
|o1 = 5                          |
|                                |
|o1 : PythonObject of class int  |
+--------------------------------+
|i2 : y = pythonValue "2"        |
|                                |
|o2 = 2                          |
|                                |
|o2 : PythonObject of class int  |
+--------------------------------+
|i3 : x + y                      |
|                                |
|o3 = 7                          |
|                                |
|o3 : PythonObject of class int  |
+--------------------------------+
|i4 : x - y                      |
|                                |
|o4 = 3                          |
|                                |
|o4 : PythonObject of class int  |
+--------------------------------+
|i5 : x * y                      |
|                                |
|o5 = 10                         |
|                                |
|o5 : PythonObject of class int  |
+--------------------------------+
|i6 : x / y                      |
|                                |
|o6 = 2.5                        |
|                                |
|o6 : PythonObject of class float|
+--------------------------------+

You can also compare them.

+-----------+
|i7 : x > y |
|           |
|o7 = true  |
+-----------+
|i8 : x == y|
|           |
|o8 = false |
+-----------+

You can also perform operations on python objects and Macaulay2 things. The
results will be returned as python objects.

+------------------------------+
|i9 : x + 2                    |
|                              |
|o9 = 7                        |
|                              |
|o9 : PythonObject of class int|
+------------------------------+

Note that many keywords in Macaulay2 are mapped to a certain dunder method in
Python.  In particular,

  * + → __add__ (binary), __pos__ (unary)
  * - → __sub__ (binary), __neg__ (unary)
  * * → __mul__
  * @ → __matmul__
  * / → __truediv__
  * // → __floordiv__
  * % → __mod__
  * ^ → __pow__
  * << → __lshift__
  * >> → __rshift__
  * & → __and__
  * | → __or__
  * ^^ → __xor__
  * and → __and__
  * or → __or__
  * xor → __xor__

Methods that use a python object:
=================================

  * ?? PythonObject (missing documentation)
  * abs(PythonObject) -- absolute value of a
    python object
  * ceiling(PythonObject) -- ceiling of a
    python object
  * describe(PythonObject) (missing documentation)
  * expression(PythonObject) (missing documentation)
  * floor(PythonObject) -- floor of a python
    object
  * "getattr(PythonObject,String)" -- see getattr, -- get an
    attribute of a python object
  * "PythonObject @@ Thing" -- see getattr, -- get an attribute
    of a python object
  * "getitem(PythonObject,Thing)" -- see getitem, -- get
    elements of python sequences
  * "PythonObject _ Thing" -- see getitem, -- get elements of
    python sequences
  * "hasattr(PythonObject,String)" -- see hasattr, -- whether a
    python object has an attribute
  * help(PythonObject) -- documentation for
    python object
  * "isMember(PythonObject,PythonObject)" -- see
    isMember(Thing,PythonObject), -- test
    membership in a python object
  * isMember(Thing,PythonObject), --
    test membership in a python object
  * iterator(PythonObject) -- get iterator
    of iterable python object
  * length(PythonObject) -- returns the length
    of a python object
  * net(PythonObject) (missing documentation)
  * next(PythonObject) -- retrieve the next item
    from a python iterator
  * "+ PythonObject"
  * "- PythonObject"
  * "PythonObject % PythonObject"
  * "PythonObject % Thing"
  * "PythonObject & PythonObject"
  * "PythonObject & Thing"
  * "PythonObject * PythonObject"
  * "PythonObject * Thing"
  * "PythonObject + PythonObject"
  * "PythonObject + Thing"
  * "PythonObject - PythonObject"
  * "PythonObject - Thing"
  * "PythonObject / PythonObject"
  * "PythonObject / Thing"
  * "PythonObject // PythonObject"
  * "PythonObject // Thing"
  * "PythonObject << PythonObject"
  * "PythonObject << Thing"
  * "PythonObject == PythonObject"
  * "PythonObject == Thing"
  * "PythonObject >> PythonObject"
  * "PythonObject >> Thing"
  * "PythonObject ? PythonObject"
  * "PythonObject ? Thing"
  * "PythonObject @ PythonObject"
  * "PythonObject @ Thing"
  * "PythonObject ^ PythonObject"
  * "PythonObject ^ Thing"
  * "PythonObject ^^ PythonObject"
  * "PythonObject ^^ Thing"
  * "PythonObject | PythonObject"
  * "PythonObject | Thing"
  * "PythonObject and PythonObject"
  * "PythonObject and Thing"
  * "PythonObject or PythonObject"
  * "PythonObject or Thing"
  * "PythonObject xor PythonObject"
  * "PythonObject xor Thing"
  * "Thing % PythonObject"
  * "Thing & PythonObject"
  * "Thing * PythonObject"
  * "Thing + PythonObject"
  * "Thing - PythonObject"
  * "Thing / PythonObject"
  * "Thing // PythonObject"
  * "Thing << PythonObject"
  * "Thing == PythonObject"
  * "Thing >> PythonObject"
  * "Thing ? PythonObject"
  * "Thing @ PythonObject"
  * "Thing ^ PythonObject"
  * "Thing ^^ PythonObject"
  * "Thing | PythonObject"
  * "Thing and PythonObject"
  * "Thing or PythonObject"
  * "Thing xor PythonObject"
  * PythonObject %= Thing (missing documentation)
  * PythonObject &= Thing (missing documentation)
  * PythonObject *= Thing (missing documentation)
  * PythonObject += Thing (missing documentation)
  * PythonObject -= Thing (missing documentation)
  * PythonObject //= Thing (missing documentation)
  * PythonObject /= Thing (missing documentation)
  * PythonObject <<= Thing (missing documentation)
  * PythonObject >>= Thing (missing documentation)
  * PythonObject @= Thing (missing documentation)
  * PythonObject ^= Thing (missing documentation)
  * PythonObject ^^= Thing (missing documentation)
  * PythonObject |= Thing (missing documentation)
  * PythonObject ~ -- bitwise not of a python object
  * quotientRemainder(PythonObject,PythonObject)
    -- quotient and
    remainder of python objects
  * "quotientRemainder(PythonObject,Thing)" -- see
    quotientRemainder(PythonObject,PythonObject),
    -- quotient and
    remainder of python objects
  * "quotientRemainder(Thing,PythonObject)" -- see
    quotientRemainder(PythonObject,PythonObject),
    -- quotient and
    remainder of python objects
  * "round(PythonObject)" -- see round(ZZ,PythonObject),
    -- round a python object
  * "round(PythonObject,PythonObject)" -- see round(ZZ,PythonObject),
    -- round a python object
  * round(ZZ,PythonObject) -- round a
    python object
  * "PythonObject @@ Thing = Thing" -- see setattr, -- set an
    attribute of a python object
  * "setattr(PythonObject,String,Thing)" -- see setattr, -- set
    an attribute of a python object
  * "PythonObject _ Thing = Thing" -- see setitem, -- set
    elements of mutable python sequences
  * "setitem(PythonObject,Thing,Thing)" -- see setitem, -- set
    elements of mutable python sequences
  * texMath(PythonObject) (missing documentation)
  * toExternalString(PythonObject) (missing documentation)
  * "PythonObject Thing" -- see toFunction, -- convert
    callable python objects to Macaulay2 functions
  * "toFunction(PythonObject)" -- see toFunction, -- convert
    callable python objects to Macaulay2 functions
  * "toPython(PythonObject)" -- see toPython, -- convert
    Macaulay2 things to Python objects
  * toString(PythonObject) (missing documentation)
  * truncate(PythonObject) -- truncate a
    python object
  * value(PythonObject) -- convert python
    objects to Macaulay2 things

For the programmer
==================

The object PythonObject, is a type (Macaulay2Doc),
with ancestor class Thing (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:130:0.

PythonObject ~ -- bitwise not of a python object
************************************************

  * Operator: ~ (Macaulay2Doc),
  * Usage:
        x~
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object, the bitwise not of x;

Description
===========

This calls Python's special __invert__ method.

+------------------------------+
|i1 : (toPython 5)~            |
|                              |
|o1 = -6                       |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * PythonObject ~ -- bitwise not of a python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:370:0.

pythonValue -- execute Python source code from a string
*******************************************************

  * Usage:
        pythonValue s
  * Inputs:
      * s, a string (Macaulay2Doc), or a sequence (Macaulay2Doc),
        containing Python source code;
  * Outputs:
      * a python object, the return value of the given
        code;

Description
===========

This function a is wrapper around the function PyRun_String (see
https://docs.python.org/3/c-api/veryhigh.html#c.PyRun_String ) from the Python
C API.

+------------------------------+
|i1 : pythonValue "2 + 2"      |
|                              |
|o1 = 4                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+

If a sequence is given, then its elements are converted to strings using
toString (Macaulay2Doc), and then joined using concatenate (Macaulay2Doc).
You can see the expression sent to the Python
interpreter by setting debugLevel (Macaulay2Doc), to a
positive value.

+------------------------------+
|i2 : debugLevel = 1           |
|                              |
|o2 = 1                        |
+------------------------------+
|i3 : x = 5                    |
|                              |
|o3 = 5                        |
+------------------------------+
|i4 : pythonValue("3 + ", x)   |
| -- python command: 3 + 5     |
|                              |
|o4 = 8                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+

See also
========

  * runSimpleString -- execute Python source code from
    a string in __main__

Ways to use pythonValue:
========================

  * "pythonValue(Sequence)"
  * "pythonValue(String)"

For the programmer
==================

The object pythonValue, is a method function with a single argument (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:226:0.

quotientRemainder(PythonObject,PythonObject) -- quotient and remainder of python objects
****************************************************************************************

  * Function: quotientRemainder (Macaulay2Doc),
  * Usage:
        quotientRemainder(x, y)
  * Inputs:
      * x, a python object,
      * y, a python object,
  * Outputs:
      * a sequence (Macaulay2Doc), a pair of two python
        objects;

Description
===========

The quotient and remainder when x is divided by y.  This calls Python's
built-in divmod function.

+-----------------------------------------------+
|i1 : quotientRemainder(toPython 37, toPython 5)|
|                                               |
|o1 = (7, 2)                                    |
|                                               |
|o1 : Sequence                                  |
+-----------------------------------------------+
|i2 : class \ oo                                |
|                                               |
|o2 = (PythonObject, PythonObject)              |
|                                               |
|o2 : Sequence                                  |
+-----------------------------------------------+

If just one of the arguments is a python object, then the other is converted to
a python object using toPython.

+--------------------------------------+
|i3 : quotientRemainder(toPython 37, 5)|
|                                      |
|o3 = (7, 2)                           |
|                                      |
|o3 : Sequence                         |
+--------------------------------------+
|i4 : class \ oo                       |
|                                      |
|o4 = (PythonObject, PythonObject)     |
|                                      |
|o4 : Sequence                         |
+--------------------------------------+

Ways to use this method:
========================

  * quotientRemainder(PythonObject,PythonObject)
    -- quotient and
    remainder of python objects
  * "quotientRemainder(PythonObject,Thing)"
  * "quotientRemainder(Thing,PythonObject)"
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:701:0.

round(ZZ,PythonObject) -- round a python object
***********************************************

  * Function: round (Macaulay2Doc),
  * Usage:
        round(n, x)
        round x
  * Inputs:
      * n, an integer (Macaulay2Doc),
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in round function, which round x to n decimal places,
or to the nearest integer if n is not given.

+--------------------------------+
|i1 : x = (import "math")@@pi    |
|                                |
|o1 = 3.141592653589793          |
|                                |
|o1 : PythonObject of class float|
+--------------------------------+
|i2 : round x                    |
|                                |
|o2 = 3                          |
|                                |
|o2 : PythonObject of class int  |
+--------------------------------+
|i3 : round(3, x)                |
|                                |
|o3 = 3.142                      |
|                                |
|o3 : PythonObject of class float|
+--------------------------------+

Ties are broken by round half to even.

+------------------------------+
|i4 : round toPython 2.5       |
|                              |
|o4 = 2                        |
|                              |
|o4 : PythonObject of class int|
+------------------------------+
|i5 : round toPython 3.5       |
|                              |
|o5 = 4                        |
|                              |
|o5 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * "round(PythonObject)"
  * "round(PythonObject,PythonObject)"
  * round(ZZ,PythonObject) -- round a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:732:0.

runSimpleString -- execute Python source code from a string in __main__
***********************************************************************

  * Usage:
        runSimpleString s
  * Inputs:
      * s, a string (Macaulay2Doc), containing Python source
        code;

Description
===========

This function a is wrapper around the function PyRun_SimpleString (see
https://docs.python.org/3/c-api/veryhigh.html#c.PyRun_SimpleString ) from the
Python C API.  Note that, unlike pythonValue, it has no
return value.

+---------------------------------------------+
|i1 : runSimpleString "print('Hello, world!')"|
+---------------------------------------------+

See also
========

  * pythonValue -- execute Python source code from a string

For the programmer
==================

The object runSimpleString, is a compiled function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:247:0.

setattr -- set an attribute of a python object
**********************************************

  * Usage:
        setattr(x, y, e)
        x@@y = e
  * Inputs:
      * x, a python object,
      * y, a string (Macaulay2Doc),
      * e, a thing (Macaulay2Doc),

Description
===========

This is equivalent to the Python setattr (see
https://docs.python.org/3/library/functions.html#setattr ) function.  Note that
e is converted to a Python object using toPython.

+---------------------------------+
|i1 : math = import "math"        |
|                                 |
|o1 = <module 'math' (built-in)>  |
|                                 |
|o1 : PythonObject of class module|
+---------------------------------+
|i2 : setattr(math, "pi", 22/7)   |
+---------------------------------+
|i3 : math@@pi                    |
|                                 |
|o3 = 3.142857142857143           |
|                                 |
|o3 : PythonObject of class float |
+---------------------------------+

As with getattr, when using the shortcut @@, y need not be a
string.

+--------------------------------+
|i4 : math@@e = 19/7             |
+--------------------------------+
|i5 : math@@e                    |
|                                |
|o5 = 2.7142857142857144         |
|                                |
|o5 : PythonObject of class float|
+--------------------------------+

Ways to use setattr:
====================

  * "setattr(PythonObject,String,Thing)"

For the programmer
==================

The object setattr, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:624:0.

setitem -- set elements of mutable python sequences
***************************************************

  * Usage:
        setitem(x, y, e)
        x_y = e
  * Inputs:
      * x, a python object,
      * y, a thing (Macaulay2Doc),
      * e, a thing (Macaulay2Doc),

Description
===========

You may set elements of mutable python sequences using setitem or the shortcut
_.  This is equivalent to square brackets ([]) in Python. For example, this
works for lists.

+--------------------------------+
|i1 : x = pythonValue "[1,2,3,4]"|
|                                |
|o1 = [1, 2, 3, 4]               |
|                                |
|o1 : PythonObject of class list |
+--------------------------------+
|i2 : setitem(x, 0, 5)           |
+--------------------------------+
|i3 : x                          |
|                                |
|o3 = [5, 2, 3, 4]               |
|                                |
|o3 : PythonObject of class list |
+--------------------------------+

It also works for dictionaries.

+------------------------------------------+
|i4 : x = pythonValue "{'spam':1,'eggs':2}"|
|                                          |
|o4 = {'spam': 1, 'eggs': 2}               |
|                                          |
|o4 : PythonObject of class dict           |
+------------------------------------------+
|i5 : x_"ham" = 3                          |
+------------------------------------------+
|i6 : x                                    |
|                                          |
|o6 = {'spam': 1, 'eggs': 2, 'ham': 3}     |
|                                          |
|o6 : PythonObject of class dict           |
+------------------------------------------+

Ways to use setitem:
====================

  * "setitem(PythonObject,Thing,Thing)"

For the programmer
==================

The object setitem, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:193:0.

stmt
****

For the programmer
==================

The object stmt (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

stmtexpr
********

For the programmer
==================

The object stmtexpr (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

symbols
*******

For the programmer
==================

The object symbols (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

toFunction -- convert callable python objects to Macaulay2 functions
********************************************************************

  * Usage:
        toFunction x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a function closure (Macaulay2Doc),

Description
===========

This function will convert a Python object into a Macaulay2 function.

+-----------------------------------+
|i1 : math = import "math"          |
|                                   |
|o1 = <module 'math' (built-in)>    |
|                                   |
|o1 : PythonObject of class module  |
+-----------------------------------+
|i2 : pysqrt = toFunction math@@sqrt|
|                                   |
|o2 = pysqrt                        |
|                                   |
|o2 : FunctionClosure               |
+-----------------------------------+
|i3 : pysqrt 2                      |
|                                   |
|o3 = 1.4142135623730951            |
|                                   |
|o3 : PythonObject of class float   |
+-----------------------------------+

Optional arguments can be provided using options.

+---------------------------------------+
|i4 : int = toFunction pythonValue "int"|
|                                       |
|o4 = int                               |
|                                       |
|o4 : FunctionClosure                   |
+---------------------------------------+
|i5 : int("deadbeef", "base" => 16)     |
|                                       |
|o5 = 3735928559                        |
|                                       |
|o5 : PythonObject of class int         |
+---------------------------------------+

If a python object and a Macaulay2 thing are separated by a space, then
toFunction will be called on the python object and then resulting function will
be called with the Macaulay2 object as its argument.

+--------------------------------+
|i6 : math@@cos pi               |
|                                |
|o6 = -1.0                       |
|                                |
|o6 : PythonObject of class float|
+--------------------------------+

Ways to use toFunction:
=======================

  * "toFunction(PythonObject)"

For the programmer
==================

The object toFunction, is a method function (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:333:0.

toPython -- convert Macaulay2 things to Python objects
******************************************************

  * Usage:
        toPython x
  * Inputs:
      * x, a thing (Macaulay2Doc),
  * Outputs:
      * a python object,

Description
===========

Attempt to convert a Macaulay2 thing to a Python object.

+--------------------------------------------------------------------+
|i1 : toPython 2                                                     |
|                                                                    |
|o1 = 2                                                              |
|                                                                    |
|o1 : PythonObject of class int                                      |
+--------------------------------------------------------------------+
|i2 : toPython (1/2)                                                 |
|                                                                    |
|o2 = 0.5                                                            |
|                                                                    |
|o2 : PythonObject of class float                                    |
+--------------------------------------------------------------------+
|i3 : toPython pi                                                    |
|                                                                    |
|o3 = 3.141592653589793                                              |
|                                                                    |
|o3 : PythonObject of class float                                    |
+--------------------------------------------------------------------+
|i4 : toPython ii                                                    |
|                                                                    |
|o4 = 1j                                                             |
|                                                                    |
|o4 : PythonObject of class complex                                  |
+--------------------------------------------------------------------+
|i5 : toPython "foo"                                                 |
|                                                                    |
|o5 = foo                                                            |
|                                                                    |
|o5 : PythonObject of class str                                      |
+--------------------------------------------------------------------+
|i6 : toPython {1, 2, 3, 4}                                          |
|                                                                    |
|o6 = [1, 2, 3, 4]                                                   |
|                                                                    |
|o6 : PythonObject of class list                                     |
+--------------------------------------------------------------------+
|i7 : toPython (1, 2, 3, 4)                                          |
|                                                                    |
|o7 = (1, 2, 3, 4)                                                   |
|                                                                    |
|o7 : PythonObject of class tuple                                    |
+--------------------------------------------------------------------+
|i8 : toPython hashTable {"foo" => "bar"}                            |
|                                                                    |
|o8 = {'foo': 'bar'}                                                 |
|                                                                    |
|o8 : PythonObject of class dict                                     |
+--------------------------------------------------------------------+
|i9 : toPython set {1, 2, 3, 4}                                      |
|                                                                    |
|o9 = {1, 2, 3, 4}                                                   |
|                                                                    |
|o9 : PythonObject of class set                                      |
+--------------------------------------------------------------------+
|i10 : toPython true                                                 |
|                                                                    |
|o10 = True                                                          |
|                                                                    |
|o10 : PythonObject of class bool                                    |
+--------------------------------------------------------------------+
|i11 : toPython null                                                 |
|                                                                    |
|o11 = None                                                          |
|                                                                    |
|o11 : PythonObject of class NoneType                                |
+--------------------------------------------------------------------+
|i12 : m2sqrt = x -> (                                               |
|          print "calling Macaulay2 code from Python!";              |
|          sqrt x)                                                   |
|                                                                    |
|o12 = m2sqrt                                                        |
|                                                                    |
|o12 : FunctionClosure                                               |
+--------------------------------------------------------------------+
|i13 : pysqrt = toPython m2sqrt                                      |
|                                                                    |
|o13 = <built-in method m2sqrt of PyCapsule object at 0x7f9ae50342a0>|
|                                                                    |
|o13 : PythonObject of class builtin_function_or_method              |
+--------------------------------------------------------------------+
|i14 : pysqrt 2                                                      |
|calling Macaulay2 code from Python!                                 |
|                                                                    |
|o14 = 1.4142135623730951                                            |
|                                                                    |
|o14 : PythonObject of class float                                   |
+--------------------------------------------------------------------+

Ways to use toPython:
=====================

  * "toPython(Boolean)"
  * "toPython(CC)"
  * "toPython(Constant)"
  * "toPython(Function)"
  * "toPython(HashTable)"
  * "toPython(Nothing)"
  * "toPython(PythonObject)"
  * "toPython(QQ)"
  * "toPython(RR)"
  * "toPython(Sequence)"
  * "toPython(Set)"
  * "toPython(String)"
  * "toPython(VisibleList)"
  * "toPython(ZZ)"

For the programmer
==================

The object toPython, is a method function with a single argument (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:510:0.

truncate(PythonObject) -- truncate a python object
**************************************************

  * Function: truncate (Macaulay2Doc),
  * Usage:
        truncate x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a python object,

Description
===========

This calls Python's built-in math.trunc function, which rounds toward zero.

+------------------------------+
|i1 : truncate toPython 5.8    |
|                              |
|o1 = 5                        |
|                              |
|o1 : PythonObject of class int|
+------------------------------+
|i2 : truncate toPython(-5.8)  |
|                              |
|o2 = -5                       |
|                              |
|o2 : PythonObject of class int|
+------------------------------+

Ways to use this method:
========================

  * truncate(PythonObject) -- truncate a
    python object
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:752:0.

val
***

For the programmer
==================

The object val (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.

value(PythonObject) -- convert python objects to Macaulay2 things
*****************************************************************

  * Function: value (Macaulay2Doc),
  * Usage:
        value x
  * Inputs:
      * x, a python object,
  * Outputs:
      * a thing (Macaulay2Doc), the Macaulay2 equivalent of x;

Description
===========

This function attempts to convert x to its corresponding Macaulay2 equivalent.

+--------------------------------------------------------------------+
|i1 : value pythonValue "[1, 3.14159, 'foo', (1,2,3), {'foo':'bar'}]"|
|                                                                    |
|o1 = {1, 3.14159, foo, (1, 2, 3), HashTable{"foo" => bar}}          |
|                                                                    |
|o1 : List                                                           |
+--------------------------------------------------------------------+
|i2 : class \ oo                                                     |
|                                                                    |
|o2 = {ZZ, RR, String, Sequence, HashTable}                          |
|                                                                    |
|o2 : List                                                           |
+--------------------------------------------------------------------+

Since the type of x is not initially known, a sequence of hooks (Macaulay2Doc),
are used to determine its type and then convert it.

+--------------------------------------------------------------------------+
|i3 : hooks value                                                          |
|                                                                          |
|o3 = {0 => (value, PythonObject, Strategy => unknown -> PythonObject)    }|
|     {1 => (value, PythonObject, Strategy => function -> FunctionClosure)}|
|     {2 => (value, PythonObject, Strategy => Counter -> Tally)           }|
|     {3 => (value, PythonObject, Strategy => dict -> HashTable)          }|
|     {4 => (value, PythonObject, Strategy => set -> Set)                 }|
|     {5 => (value, PythonObject, Strategy => list -> List)               }|
|     {6 => (value, PythonObject, Strategy => tuple -> Sequence)          }|
|     {7 => (value, PythonObject, Strategy => str -> String)              }|
|     {8 => (value, PythonObject, Strategy => complex -> CC)              }|
|     {9 => (value, PythonObject, Strategy => float -> RR)                }|
|     {10 => (value, PythonObject, Strategy => int -> ZZ)                 }|
|     {11 => (value, PythonObject, Strategy => bool -> Boolean)           }|
|                                                                          |
|o3 : NumberedVerticalList                                                 |
+--------------------------------------------------------------------------+

If no conversion can be done, then x is returned.

+-------------------------------+
|i4 : pythonValue "int"         |
|                               |
|o4 = <class 'int'>             |
|                               |
|o4 : PythonObject of class type|
+-------------------------------+
|i5 : value oo                  |
|                               |
|o5 = <class 'int'>             |
|                               |
|o5 : PythonObject of class type|
+-------------------------------+

Users may add additional hooks using addHook (Macaulay2Doc), or
the convenience function addPyToM2Function.

Ways to use this method:
========================

  * value(PythonObject) -- convert python
    objects to Macaulay2 things
-------------------------------------------------------------------------------

The source of this document is in Python/doc.m2:424:0.

valuestring
***********

For the programmer
==================

The object valuestring (missing documentation) is a symbol (Macaulay2Doc).

-------------------------------------------------------------------------------

The source of this document is in
/home/runner/work/M2/M2/M2/BUILD/build/Macaulay2/packages/currentString:2:0.