pnotepad.org forums

Programmer's Notepad Forums

1. 

   dandersahn
   Member

   Is there any documentation out there for PyPN? Some things that worked in older versions don't seem to work in the latest (0.5). I'm trying to figure out the correct function call to get the current document name, for example. pn.CurrentDoc().GetFileName() used to work, but doesn't seem to any more.

   Posted 4 years ago #
2. 

   simon
   PN Developer

   There's no real documentation yet, but Python provides it's own:

   dir(pn)

   wrapped up with:

   pn.AddOutput(str(dir(pn)))

   gives:

   ['AddOutput', 'AppPath', 'ClearOutput', 'CurrentDoc', 'FindNextResult',
   'GetUserSearchOptions', 'IDCANCEL', 'IDNO', 'IDOK', 'IDYES', 'IDocument',
   'ISearchOptions', 'InputBox', 'MB_ICONERROR', 'MB_ICONINFORMATION', 'MB_ICONQUESTION',
   'MB_OK', 'MB_OKCANCEL', 'MB_YESNO', 'MB_YESNOCANCEL', 'MessageBox', 'NewDocument',
   'OpenDocument', 'RegisterScript', 'SetOutputBasePath', 'SetOutputDefaultParser',
   'SetOutputRegEx', '__doc__', '__name__']

   We can then find out what's available in the document by calling:

   pn.AddOutput(str(dir(pn.CurrentDoc())))

   ['CanSave', 'Close', 'CurrentScheme', 'FileName', 'FindNext', 'IsValid', 'Modified',
   'Replace', 'ReplaceAll', 'Save', 'SendMessage', 'Title', <omitted for brevity>]

   The problem you're seeing is that a few things have changed to use properties instead of methods, so your example line should now be:

   pn.CurrentDoc().FileName

   Posted 4 years ago #
3. 

   mirkosoft
   Member

   Does someone know a way to generate such a "documentation" automatically?

   Posted 4 years ago #
4. 

   simon
   PN Developer

   I'm looking into it, would be good to have some browsable docs instead of forcing "learn by example"!

   Posted 4 years ago #
5. 

   d_henderson
   Member

   It looks like Boost provides some assistance in creating documentation by adding generated function signatures (either python, c++ or both).

   From the http://www.boost.org/doc/libs/1_35_0/libs/python/doc/v2/docstring_options.html
   page, it looks like adding lines like:

   docstring_options doc_options(true,true,false);

   will create doc strings with user defined plus python function signatures for functions in a module.

   It is not clear from the examples if a single docstring_options object following the start of a module is sufficient to generate docstrings for the classes in the module as well.

   With doc strings in the Boost generated modules, we would now have more than the absolute mimimal content to display using pydoc.

   I have written a small pypn script to display pydoc strings for the pn, pypn and scintilla modules into a document. I'll post that in a separate topic.

   I might be able to generate a patch for the suggested changes, but I am not setup to run builds locally.

   Posted 3 years ago #
6. 

   d_henderson
   Member

   Here is my script to display the internal documentation on the PyPN embedded code in a new editor window.

   This script executes the code for the built-in help function, redirecting its output into a new document window.

   Any docstrings for the pn, scintilla, pypn modules and user supplied scripts will be used to generate pydoc style documentation.

   """Provide the ApiInfo script to Programmer's Notepad.
   
   Author: Doug Henderson
   """
   
   import pn, scintilla, pypn, debug, scripts
   from pypn.decorators import script
   
   import sys, pprint, pydoc, traceback
   
   class Input(object):
       """dummy input file-like object"""
       def __init__(self):
           self._closed = False
       def close(self):
           self._closed = True
       def read(self,size=None):
           return ''
       def readline(self):
           return '\n'
       def _get_closed(self): return self._closed
       def _set_closed(self,_closed): self._closed = _closed
       closed = property(_get_closed,_set_closed,None,
           "True if the file is closed")
   
   class NewDocument(object):
       """file-like interface to new Scintilla document editor
       NewDocument() -> file object
   
       Open a file on a new Scintilla document editor.
       Provide the ability to add text to a new document
       editor using the python file idiom."""
       def __init__(self):
           """x.__init__(...) initializes x; see x.__class__.__doc__ for signature"""
           self._closed = False
           self._softspace = 0
           doc = pn.NewDocument(None)
           self.__editor = scintilla.Scintilla(pn.CurrentDoc())
           self.__editor.BeginUndoAction()
   
       def close(self):
           """close() -> None or (perhaps) an integer.  Close the file.
   
           Sets data attribute .closed to True.  A closed file cannot be used for
           further I/O operations.  close() may be called more than once without
           error.  Some kinds of file objects (for example, opened by popen())
           may return an exit status upon closing."""
           if not self._closed:
               self.__editor.EndUndoAction()
           self._closed = True
           self.__editor = None
   
       def flush(self):
           """flush() -> None.  Flush the internal I/O buffer. In this case, a no-op"""
           pass
   
       def write(self,s):
           """write(str) -> None.  Write string str to file.
   
           Note that due to buffering, flush() or close() may be needed before
           the file on disk reflects the data written."""
           if self._closed:
               return
           self.__editor.AppendText(len(s), s)
   
       def writelines(self,ss):
           """writelines(sequence_of_strings) -> None.  Write the strings to the file.
   
           Note that newlines are not added.  The sequence can be any iterable object
           producing strings. This is equivalent to calling write() for each string."""
           for s in ss:
               self.write(s)
   
       def _get_closed(self): return self._closed
       def _set_closed(self,_closed): self._closed = _closed
       closed = property(_get_closed,_set_closed,None,
           "True if the file is closed")
   
       def _get_softspace(self): return self._softspace
       def _set_softspace(self,_softspace): self._softspace = _softspace
       softspace = property(_get_softspace,_set_softspace,None,
           "flag indicating that a space needs to be printed; used by print")
   
   def write_sep(f,s=None):
       """write an output section separator"""
       print >> f, ''
       if s:
           print >> f, s + ' ' + '='*50
       else:
           print >> f, '='*50
   
   @script("ApiInfo", "MyScripts")
   def api_info():
       """api_info() - provide the Programmer's Notepad script ApiInfo.
       Display PN python API Information (version 4)
       in a new document."""
       input = Input()
       output = NewDocument()
       sys_stdin = sys.stdin
       sys_stdout = sys.stdout
       try:
           sys.stdin = input
           sys.stdout = output
           try:
               pd = pydoc.Helper(input,output)
   
               # document embedded modules
               write_sep(output,'pn')
               pd.help(pn)
   
               write_sep(output,'scintilla')
               pd.help(scintilla)
   
               write_sep(output,'pypn')
               pd.help(pypn)
               write_sep(output)
               pprint.pprint(pypn,stream=output)
               write_sep(output)
               pprint.pprint(dir(pypn),stream=output)
   
               # document subordinate modules, e.g. pypn.*
               write_sep(output)
               for d in dir(pypn):
                   if not d.startswith('_'):
                       m = 'pypn.' + d
                       write_sep(output,m)
                       pd.help(m)
   
               write_sep(output,'debug')
               pd.help(debug)
   
               # document python scripts module tree
               write_sep(output,'scripts')
               pd.help(scripts)
               write_sep(output)
               pprint.pprint(scripts,stream=output)
               write_sep(output)
               pprint.pprint(dir(scripts),stream=output)
               write_sep(output)
               for d in dir(scripts):
                   if not d.startswith('_'):
                       m = 'scripts.' + d
                       write_sep(output,m)
                       pd.help(m)
           except:
               # just in case, show a traceback
               print >> output, 'Exception in ApiInfo'
               traceback.print_exc(file=output)
       finally:
           # restore original values of system standard files
           sys.stdin = sys_stdin
           sys.stdout = sys_stdout
   
       output.close()
       output = None
       input.close()
       input = None
   
   # -30-

   Posted 3 years ago #
7. 

   simon
   PN Developer

   That is awesome, I had the start of something similar like this:

   import pydoc
   import pn
   import pypn
   
   def document(module):
   	inner = dir(module)
   	for thing in inner:
   		if thing[0] != '_':
   			pydoc.writedoc(module.__name__ + "." + thing)
   	pydoc.writedoc(module)
   
   # Document the PyPN modules:
   document(scintilla)
   document(pypn)
   document(debug)
   pydoc.writedoc(pn)

   This just writes HTML files with similar content, which I was hoping to eventually put onto the web. You've got some nice classes coming along for working with PN using more pythonic interfaces - it would be good to get something like these included in the base distribution.

   Posted 3 years ago #

RSS feed for this topic

Reply

You must log in to post.