extra/python/python-docs.factor

   1 USING: alien destructors help.markup help.syntax python python.throwing
   2 quotations ;
   3 IN: python
   4
   5 HELP: py-initialize
   6 { $description "Initializes the python binding. This word must be called before any other words in the api can be used" } ;
   7
   8 HELP: py-finalize
   9 { $description "Finalizes the python binding. After this word is called the api must not be used anymore." } ;
  10
  11 HELP: >py
  12 { $values { "obj" "a factor object" } { "py-obj" "a python object" } }
  13 { $description "Converts a factor objects to its most fitting python representation." }
  14 { $examples
  15   { $example
  16     "USING: arrays prettyprint python sequences ;"
  17     "10 <iota> >array >py py> ."
  18     "{ 0 1 2 3 4 5 6 7 8 9 }"
  19   }
  20 }
  21 { $see-also py> } ;
  22
  23 HELP: quot>py-callback
  24 { $values { "quot" { $quotation ( args kw -- ret ) } } { "alien" alien } }
  25 { $description "Creates a python-compatible alien callback from a quotation." }
  26 { $examples
  27   "This is how you create a callback which returns the double of its first positional parameter:"
  28   { $unchecked-example
  29     "USING: python ;"
  30     ": double-fun ( -- alien ) [ drop first 2 * ] quot>py-callback ;"
  31   }
  32 } ;
  33
  34 HELP: with-quot>py-cfunction
  35 { $values { "alien" alien } { "quot" quotation } }
  36 { $description "Wrapper for " { $link with-callback } " to be used when passing functions as arguments to Python functions. It should be used in conjunction with " { $link quot>py-callback } " which creates the callbacks this word consumes." } ;
  37
  38 HELP: python-error
  39 { $error-description "When Python throws an exception, it is translated to this Factor error. " { $slot "type" } " is the class name of the python exception object, " { $slot "message" } " its string and " { $slot "traceback" } " a sequence of traceback lines, if the error has one, or " { $link f } " otherwise." } ;
  40
  41 ARTICLE: "python" "Python binding"
  42 "The " { $vocab-link "python" } " vocab and its subvocabs implements a simple binding for libpython, allowing factor code to call native python."
  43 $nl
  44 "Converting to and from Python:"
  45 { $subsections >py py> quot>py-callback }
  46 "Error handling:"
  47 { $subsections python-error }
  48 "Initialization and finalization:"
  49 { $subsections py-initialize py-finalize }
  50 "Module management:"
  51 { $subsections py-import }
  52 "The vocab " { $vocab-link "python.syntax" } " implements a higher level factorific interface on top of the lower-level constructs in this vocab. Prefer to use that vocab most of the time."
  53 { $notes "Sometimes the embedded python interpreter can't find or finds the wrong load path to it's module library. To counteract that problem it is recommended that the " { $snippet "PYTHONHOME" } " environment variable is set before " { $link py-initialize } " is called. E.g:" }
  54 { $code "\"C:/python27-64bit/\" \"PYTHONHOME\" set-os-env" }
  55 { $warning "All code that calls Python words should always be wrapped in a " { $link with-destructors } " context. The reason is that the words add references to Pythons internal memory heap which are removed when the destructors trigger." } ;
  56
  57 ABOUT: "python"