Zope-2.9.4-retire_zpkg/0000755000175000017500000000000010447234075014700 5ustar tseavertseaverZope-2.9.4-retire_zpkg/Extensions/0000755000175000017500000000000010447233606017036 5ustar tseavertseaverZope-2.9.4-retire_zpkg/Extensions/README.txt0000644000175000017500000000011310050234363020516 0ustar tseavertseaverPlace files containing code for External Method objects in this directory. Zope-2.9.4-retire_zpkg/doc/0000755000175000017500000000000010447233670015445 5ustar tseavertseaverZope-2.9.4-retire_zpkg/doc/PLATFORMS/0000755000175000017500000000000010447233607017014 5ustar tseavertseaverZope-2.9.4-retire_zpkg/doc/PLATFORMS/README.txt0000644000175000017500000000022510050234363020477 0ustar tseavertseaverThis directory is to collect notes that people send us on using Zope on Platforms that we (Digital Creations) don't have and can't support directly. Zope-2.9.4-retire_zpkg/doc/PLATFORMS/AIX.txt0000644000175000017500000000156410050234363020172 0ustar tseavertseaver from Thiebaut Champenier "python wo_pcgi.py" doesn't build the extensions correctly due to linking problems. To fix it, I just SymLinked ld_so_aix, makexp_aix and python.exp (found in /Modules/) into each of the dirs in /python/lib that contain .c files... and it worked just great. But I'm sure it's not the best solution from Wolfgang Roesner (reporting segfaults and a fix) The default stack size for a pthread on AIX (at least in my configuration) is 96kB. On Solaris it's 1M. As soon as I explicitly set the initial stack size to 1M the problem went away and it appears as if Zope is up and running. Unfortunately I really had to change "thread_pthread.h" in Python which obviously is not a nice thing to do as I now have a need for my own private version of Python. But at least I have a running version of Zope on AIX. Zope-2.9.4-retire_zpkg/doc/PLATFORMS/BSD.txt0000644000175000017500000000161010050234363020151 0ustar tseavertseaverSteps to building python for use with Zope on FreeBSD to avoid segmentation faults (by Andrew Sawyers for Pythons up to 2.3). The default thread stack size for FreeBSD is too small; when building Python for use with Zope it is often necessary to increase the thread stack size to avoid segmentation faults. There are two ways which you can increase the default python thread stack size. Way #1: In your Python source directory: * >cd Python * >edit thread_pthreads.h at the top of the header file, add #define THREAD_STACK_SIZE 1000000 * >save * >cd ..; ./configure Way #2: In your Python source directory: * >./configure * >make OPT="-DNDEBUG -g -O3 -Wall -Wstrict-prototypes -DTHREAD_STACK_SIZE=1000000" Passing in the define or adding the define to your source solves all experiences I have experienced with Zope segfaulting while running on my FreeBSD platforms. Zope-2.9.4-retire_zpkg/doc/WEBSERVER.txt0000644000175000017500000004336410344050403017547 0ustar tseavertseaverUsing Zope with an existing web server -------------------------------------- While Zope comes with a web server, you may wish to use it with an existing web server. Use Persistent CGI (PCGI) or FastCGI to allow your existing web server to work with Zope on Unix and Windows. Roughly, PCGI is a protocol for translating CGI requests from a web server into Zope requests. CGI requests are traditionally one shot events; the web server handles a request for a CGI script by spawning a new process to handle the requests, returning the results of the request when the process dies. Zope is a long running process, which means that it does not start up and die on each request like traditional CGI programs. If it did, each request would take far too long due to the time to start and stop an application server like Zope. Thus, PCGI is one of the options for gatewaying from the separate CGI processes to the Zope long running process. FastCGI is very similar to PCGI. Where PCGI has a "wafer-thin" external CGI program to connect Apache and Zope, FastCGI has an Apache module. This saves the so called "fork tax" which is incurred when Apache forks to execute the PCGI CGI program. Using Zope in multi-threaded mode with ZServer ---------------------------------------------- ZServer is a general purpose TCP server for publishing Zope objects over various transport protocols. For Zope to run multi-threaded, you must run ZServer. ZServer is based on Sam Rushing's Medusa software. The benefit of using Medusa as the ZServer core is that it is not protocol specific (Medusa provides libraries to program for any protocol) and it is easily extensible. Because Medusa is written in Python, is extremely high performance by design, and comes with an HTTP and FTP server, we chose it for the Zope core. It is not necessary, however, for ZServer to actually listen for incoming HTTP requests. If you want Apache to do the actual listening and serving, then you can use ZServer's PCGI or FastCGI components to communicate with Apache. PCGI PCGI is deprecated and should not be used anymore. To install PCGI, please get the PCGI support package from the Zope 2.6 tarball (it no longer ships with Zope 2.7), and read the pcgi/README file from that package. To run ZServer with PCGI, you must configure Zope with a PCGI server. You can do this by adding a section to the etc/zope.conf file like this:: address /path/to/PCGI/resource/file Note, you must have gone through the directions in 'INSTALL.txt' for this to work. This command will cause Zope to start with a PCGI server as well as any other servers you specify in the zope.conf file. For PCGI to work, the webserver and Zope must agree on a PCGI resource file. Now the Zope long running process is started up, and the PCGI component is loaded and ready to receive CGI requests from your webserver. The installation process should create a 'Zope.cgi' PCGI file. Copy the 'Zope.cgi' file to your web server's 'cgi-bin' directory. On Unix you can also create a symbolic link to 'Zope.cgi' from your cgi-bin directory. For example:: ln -s /home/amos/Zope/Zope.cgi /usr/local/apache/cgi-bin/Zope At this point you should perform any other steps you web server requires to install and configure a CGI script. Note: For more information on PCGI check out Jeff Bauer's "PCGI pages", http://starship.python.net/crew/jbauer/persistcgi/. When your Zope.cgi file is correctly configured as a CGI script with your web server, you are ready to access Zope through the web. You should point your browser at: 'http://youmachine.example.com:8998/cgi-bin/Zope.cgi/manage' (Your URL maybe be different depending on how your web server is configured.) You should be prompted to enter a username and password. Enter the Zope "super manager" name and password. Note: Apache requires some tricky configuration to get it to pass the HTTP authentication header information to Zope. See the section 'Zope authentication with existing web servers'. There is an Apache module for Zope/PCGI: http://www.zope.org/Members/phd/mod_pcgi2/ One can easily compile and configure it. It passes the HTTP authentication header and other environment variables. It supports virtual hosting. FastCGI FastCGI is deprecated and should not be used anymore. FastCGI is relatively easy to set up if you have installed an Apache module before. If you haven't, don't worry, it isn't difficult. It comes with straightforward instructions. You will need to download the mod_fastcgi module from FastCGI.com: http://www.fastcgi.com/ A version more recent than 2.2.2 is needed. Extract the archive and follow the directions in its 'INSTALL' file. Using the 'DSO' method is usually easiest. Next, Zope must be set up to use FastCGI. You must decide whether you want to use FastCGI via a Unix domain socket or a TCP port. You will have to use a TCP port if you are using a Win32 box, or any other operating system that does not provide Unix domain sockets (sockets in the filesystem). It is also the method you must use if Apache and Zope reside on different computers. You will need to select a port number. This is arbitrary, but it must not already be in use, and if you are not the super-user, it must be a sufficiently high number. For illustrative purposes, I will use 8889. Unix domain sockets do not open a TCP port, which may be significant in some tight-security situation, but it requires slightly more setup, and so it is slightly less fool-proof. You will need to select a location and filename for the socket. Likely options are '/tmp/zope.soc' or within Zope's 'var' directory. Make sure that both Zope and Apache will have adequate file permissions to read and write to the socket. For illustrative purposes, I will use '/tmp/zope.soc'. This can be configured by adding a fast-cgi section in your etc/zope.conf file. The section should look like this for a TCP port:: address localhost:8889 To use a Unix domain socket instead, specify the path of the socket file instead of a [hostname:]port:: address /tmp/zope.soc You can start Zope at this point by running the 'runzope' script:: $ ./bin/runzope Next, Apache must be set up to pass FastCGI requests to Zope. This is done with a 'FastCgiExternalServer' directive in Apache's httpd.conf. By using 'FastCgiExternalServer' we are telling FastCGI that we'll be launching and killing the long-running process manually. It goes at the beginning of 'Section 2'. This directive will look like this for a TCP port configuration:: FastCgiExternalServer /PATH/TO/apache/htdocs/zope \ -host localhost:8889 \ -pass-header Authorization ...or like this for a socket configuration:: FastCgiIpcDir /tmp FastCgiExternalServer /PATH/TO/apache/htdocs/zope \ -socket zope.soc \ -pass-header Authorization The FastCgiIpcDir directive is needed to tell FastCGI where to find the socket file. By default, FastCGI will look in /tmp/fcgi. You *cannot* specify a full path with the '-socket' option, only a filename within the FastCgiIpcDir. The first argument after the directive name is confusing. Apache maps URLs to directories and files within your 'DocumentRoot'. You must specify the name of a file within your DocumentRoot directory, but that file need not (and probably should not) actually exist. When Apache tries to serve that file, it will instead send the request through FastCGI. Make sense? Say, for instance, you want zope to be accessible from this URL: http://myserver.org/myzope Suppose further that you have Apache installed at /usr/local/apache. The directive would have to look like this:: FastCgiExternalServer /usr/local/apache/htdocs/myzope \ ... ... The next argument depends on whether you are using a TCP port or a socket. Note that the -host (port) argument requires the hostname. In the example, it's the same host as Apache runs on, but this need not be the case. If you are using a socket, make sure Apache has the appropriate privileges to find it. The last argument, '-pass-header Authorization', tells FastCGI to pass the Authorization headers to Zope. Without this, you would not be able to use the Zope web management interface, or anything else that requires authorization. (Note: This feature was not in mod_fastcgi 2.2.2) One more item must be added to the httpd.conf. Below the 'FastCgiExternServer' directive, enter the following:: SetHandler fastcgi-script ...changing '/zope' as appropriate. Using the 'http://myserver.org/myzope' example from above, it would look like this:: SetHandler fastcgi-script This creates a special case for the location specified, telling Apache to let FastCGI handle the request. That is all that is needed. Make sure Zope is running, start or restart Apache, and you are finished. Using Zope in single-threaded mode with pcgi_publisher ------------------------------------------------------ The installation process should create a 'Zope.cgi' PCGI file. Copy the 'Zope.cgi' file to your web server's cgi-bin directory. On Unix you can also create a symbolic link to 'Zope.cgi' from your cgi-bin directory. For example:: ln -s /home/amos/Zope/Zope.cgi /usr/local/apache/cgi-bin/Zope At this point you should perform any other steps you web server requires to install and configure a CGI script. Note: For more information on PCGI check out Jeff Bauer's "PCGI pages", http://starship.python.net/crew/jbauer/persistcgi/. When your Zope.cgi file is correctly configured as a CGI script with your web server, you are ready to access Zope through the web. You should point your browser at: 'http://youmachine.example.com:8998/cgi-bin/Zope.cgi/manage' (Your URL maybe be different depending on how your web server is configured.) You should be prompted to enter a username and password. Enter the Zope "super manager" name and password. Zope authentication with existing web servers --------------------------------------------- Zope normally performs both authentication and authorization of users. Some web servers don't pass authentication information to CGI scripts. If you keep getting rejected when you try to access Zope through the web with the "super manager" user name and password, there is a good chance that your web server is not passing authentication information to Zope. Getting Apache to pass authentication headers Before attempting to use your own Apache with Zope, it is highly recommended that you look at Zap. Zap is a preconfigured and precompiled version of Apache for Linux that drops right into Zope with no hassles. Even if you want to use your own Apache, or if you use it on a different platform than Linux, it is very helpful to have Zap's 'httpd.conf' file to guide you through configuring Apache. Zap can be found on the Zope website at: http://www.zope.org/Download/Releases/Zap-1.1.0 If you are using Apache you will need to convince Apache to pass authentication headers to Zope. The easiest way to do this with Apache 1.3 and above is to use mod_rewrite. Here is an example of configuration information which you would place in an Apache conf file:: # Zope configuration maps /Zope/ to the Zope.cgi CGI script RewriteEngine on RewriteCond %{HTTP:Authorization} ^(.*) RewriteRule ^/Zope(.*) /usr/local/apache/cgi-bin/Zope.cgi/$1 [e=HTTP_CGI_AUTHORIZATION:%1,t=application/x-httpd-cgi,l] Note that the RewriteRule should be one long line, and that the last character is the letter l, not the number 1. For Apache servers version 1.3b4 and above, there is an alternate way to get the server to pass through authorization headers, but you must have the ability to recompile your Apache server binary. If you pass the flag -DSECURITY_HOLE_PASS_AUTHORIZATION when compiling the server, the resulting Apache binary will allow authorization headers to pass through to CGI programs and you can avoid using the Rewrite rules described above. Allowing your server to handle authentication itself Sometimes you may prefer to handle authentication outside Zope, for example if your web server already does complex authorization, or if it seems too difficult to convince it to pass authentication information to Zope. As of 1.9, Zope began supporting a mode that allowed the web server to handle authentication. The 'REMOTE_USER' environment variable is then matched to the identity of a user object in Zope. The following provide step-by-step instructions for setting this up in Apache, allowing both the Zope "super manager" defined in the Zope 'access' file and users defined in Zope User Folders to be authenticated via the web server. Get Apache to authenticate /cgi-bin/Zope Add a directive in your Apache configuration file such as:: AuthType Basic AuthName Zope-realm AuthUserFile /usr/local/etc/httpd/conf/ru_users require valid-user Then send Apache a '-1' signal to tell it to re-read its configuration files. *Note*: The above presumes that '/cgi-bin/Zope' has been made executable by some other Apache directive in the configuration file. Ensure Apache has 'superuser' Using Apache's tools for managing a user database, make sure that the 'AuthUserFile' defined above has a valid user called 'superuser'. Get Zope to use Apache's authentication Change Zope's access file to contain just the superuser id followed by a colon, as in:: superuser: Note that this can be any value, including spaces. The only restriction is that the value must match a user defined in Apache's user database. N.B.: removing the password in the access file also enables access to the monitor for any user connecting through the localhost interface -- DISABLE THE MONITOR if using this option on any box which allows untrusted logins. Shut down Zope by doing:: kill `cat var/Main.pid` from the Zope directory. Configure Zope At this point you are able to log in using the "superuser" identity. If you want other people defined in the Apache user database to have identities in Zope, you need to add them to a User Folder (the object whose ID is acl_users). Either click on the pre-defined acl_users in the top folder or add a User Folder object to a subfolder. Specific web servers Apache * As mentioned above, Apache does not pass authorization information to CGI scripts by default. See above for information on how to deal with this situation. * There is Apache module to support PCGI (mod_pcgi2). See the section "PCGI" above for details. Netscape Servers * Like Apache, Netscape does not pass HTTP Authorization information to CGI scripts. We have a plugin at our website that addresses this. http://www.zope.org * Alternatively, you can allow the web server to perform the authentication step. See above for more information. IIS * You must turn off Windows NT Challenge/Response authentication. To do this, go to IIS Manager, right-click on the server, select Service Properties, and deselect *both* 'Windows NT Challenge/Response' and, strangely, Basic Authentication from the Password Authentication area of the Service tabbed worksheet. * IIS kindly throws out PATH_INFO when writing to its logs, so if you want to log which Zope objects are actually being accessed, you will need to investigate an ISAPI filter * An ISAPI module to support PCGI is under development. * IIS 4.0 throws away Zope's error messages by default. This behavior can create quite a few problems, including authentication problems. Microsoft prides itself on the clear error messages that IIS 4.0 presents, when the user makes a mistake. These error messages are implemented in the form of Custom Error handlers, that return a file, or URL to a user when a certain error occurs. This means, that when you forget to fill in an Id when you want to create, say, a new SQL Method, Zope's clear error message is replaced by IIS's totally irrelevant error message. Also, it completely breaks authentication when the user uses IE5.0 when trying to log into a secure area of the server. These Custom Error handlers are enabled by default. Luckily, the handlers can quite easily be switched off: Open the IIS website in the Management Console, and navigate to the folder you put the PCGI executable in. If you named your Zope installation 'Zope', it will be called 'Zope.exe'. Double-click on that file. A property page will appear. Select the 'Custom Errors' tab. Now, select every HTTP Error code in the listbox that doesn't have type 'Default', and click on the 'Set to Default' button for each one. This will disable IIS overriding the error message returned by Zope. Click OK, and voila, Zope is allowed to tell the world what it thinks went wrong. Zope-2.9.4-retire_zpkg/doc/HISTORY.txt0000755000175000017500000011515410345056075017360 0ustar tseavertseaverZope History This file contains change information for previous versions of Zope. Change information for the current release can be found in the file CHANGES.txt. Zope 2.8.4 (2005/10/26) Bugs Fixed - Collector #1927: Modified ZReST not to store rendered / warnings as persistent attributes, using volatile attributes instead as a cache. - Collector #1926: fixed a typo in _doAddUser when password encryption is enabled. - If a content object implemented any in-place numeric operators, untrusted code could call them, thus modifying the content. - If Python 2.4 is used, despite the fact that Python 2.4 is unsupported, untrusted code could use generator expressions to gain access to container items. Zope 2.8.3 (2005/10/18) Other - ZSQLMethod.manage_main: Moved the error message that warns of a non-existing or closed database connection next to the Connection ID dropdown and present it using red to increase its visibility. - Update to Docutils 0.3.9 (forgotten in Zope 2.8.2) Zope 2.8.2 (2005/10/13) Features added - Collector #1118: Added syntax to dtml-sqlgroup to support flexible generation of 'UPDATE' statements (bounty sponsored by Logicalware). - The '@' character is now allowed in object ids (RFC 1738 allows it). Bugs Fixed - OFS.Image.manage_FTPget() would str() it's .data attribute, potentially loading the whole file in memory as a string. Changed to use RESPONSE.write() iterating through the Pdata chain, just like index_html(). - When PageTemplates have a syntax error, show the traceback output in the rendered error message. - Collector #1914: Hardened 'call_with_ns' (in 'Products.PageTemplates.ZRPythonExpr') against namespaces from other callers than page templates. - Collector #1490: Added a new zope.conf option to control the character set used to encode unicode data that reaches ZPublisher without any specified encoding. - Collector #1895: omit 'var' folder from recursive traversal causing trouble with DirectoryStorage. - disabled ".. include" directive for all the ZReST product and the reStructuredText package - Collector #1888: Adjust call to 'engine.translate' to accomodate change in its signature. - Collector #1863: Prevent possibly sensitive information to leak via the TransientObject's __repr__ method. - Repaired 'handle_errors' usage for doctests, along with the supporting 'debug' argument passed to 'ZPublisher.Test.publish_module'. - Collector #1879: applied patch by Dieter Maurer to fix a bug in ac_aquire() ignoring the default argument - Collector #1864, #1906: fixed header normalization in appendHeader() - Collector #1899: fixed migration issue when using export/import for ZCatalog instances - 'ZPublisher.Test.publish' now takes a 'done_string' argument, which is written to standard error when the request completes (forward ported from Zope 2.7 branch). - Collector #556: now returns 'null' instead of 'None' for values which are None in Python (sponsored by a bounty from Logicalware). - Collector #1182: BBB Forward port fix from 2.7 branch (19 months ago!), reverting 'guarded_getitem' to pass the 'index' argument as the name to 'validate'. This change is *not* propagated to the trunk, because the resolution of #1182 specifies that the reverted behavior (i.e., passing None for item accces) is to become the standard implementation as of 2.9. - Collector #1877: skel/Products/README.txt inappropriately copied from CMF. - Collector #1871: Applied patch to support lists with records using ZTUtils.make_query() - AccessControl: creating a new user through "zpasswd inituser" did not work properly with a top-level user folder with enabled password encryption. - ZCatalog: refreshCatalog() could not be called safely from a ZEO client script - Catalog.clear(): fixed handling of _length attribute (caused import problems for some .zexp files e.g. Squishdot instances) - DateIndex now properly removes documents from both indexes if the value is None - Collector #1888: Some parts of the TALInterpreter would not pass a default when translating, yet expect a string back. This would cause an error (usually "NoneType has no attribute 'replace'") in the case the message was not translated. Zope 2.8.1 (2005/08/11) Features added - Interface: Added Z3 -> Z2 bridge utilities. This allows to migrate interfaces to Zope 3 style interfaces and bridge them back to oldstyle interfaces for backwards compatibility. Bugs Fixed - Zope2.Startup.zopectl: fork before execv when running unit tests (don't exit the shell, if run from there). - TAL: MassageIDs are now handled the same way as in zope.tal. - DocumentTemplate: ustr no longer mangles MassageIDs. Custom string types are now returned unchanged. - As developed in a long thread starting at http://mail.zope.org/pipermail/zope/2005-July/160433.html there appears to be a race bug in the Microsoft Windows socket implementation, rarely visible in ZEO and/or in ZServer/medusa/thread/select_trigger.py when multiple processes try to create an "asyncore trigger" simultaneously, most often (in stress tests) manifesting as a hung process. Windows-specific trigger code in both changed to work around this bug when it occurs. - Collector #1807: fixed memory leak in cAccessControl.guarded_getattr() Zope 2.8.1 b1 (2005/07/28) Features Added - PluginIndexes, ZCTextIndex and ZCatalog: Added some z3 interfaces. - Verbose security exception reporting has been folded into Zope, removing the need for the VerboseSecurity product. See the documentation for the "verbose-security" option in zope.conf. - "TemporaryStorage" (the storage that is used mainly to back the default sessioning database) is now MVCC capable, which essentially means that its usage will no longer generate ZODB ReadConflictErrors. Bugs Fixed - Collector #1852: fixed wrong URL construction in webdav.davcmds - Collector #1844: fixed whitespace handling in the ZMI "Find" tab - Collector #1813: removed spurious inclusion of CMFBTreeFolder. in Products/BTreeFolder2 (CMFCore will include it after 1.5, with an appropriate module alias for backward compatibility). - Replaced all transaction.commit(1) calls by transaction.savepoint() - Collector #1832: UnIndex swallowed ConflictErrors. - Collector #1815: ZCTextIndex accepts (again) sequences of strings to be indexed. - Collector #1812: Fixed key error in ZSQL ZMI/Test - Fixed CMFBTreeFolder for CMF 1.5+ - WebDAV COPY and MOVE did not call '_notifyOfCopyTo' and '_postCopy' hooks like it was done in OFS.CopySupport. Additionally added 'manage_changeOwnershipType' to make MOVE behave even closer to OFS.CopySupport. - Collector #1548: Fix 'httplib' usage in ZPublisher.Client. - Collector #1808: manage_convertIndexes no longer tries to change the index types causing some trouble with CMF. - manage_convertIndexes did not treat DateRangeIndexes and PathIndexes properly. - Updated Zope X3 to bugfix release 3.0.1 - Updated Five to bugfix release 1.0.2 (see Products/Five/CHANGES.txt) Zope 2.8.0 (2005/06/11) Bugs Fixed - Collector #1792: applied patch for broken ZClasses - doc/FAQ.txt updated: should bear some resemblance to reality now. (PCGI stuff removed; error information updated; PID information updated; upgrade procedure added; some common version questions added.) - Collector #1770: Fixed RestructuredText subtitle - Collector #1803: Fixed InitializeClass for some corner case. - Collector #1798, issue 1: ZopeTestCase no longer tries to install products that were installed by Zope during startup. - Collector #1799: Avoid lying about parent's refcount when calling back into Python code. - Collector #889: made 'and' operator for KeywordIndexes actually restrict results as expected (thanks to 'aroda' for the patch!). - Collector #1323: applied patch to fix umask problem in zdctl - Updated Five to bugfix release 1.0.1 (see Products/Five/CHANGES.txt) Zope 2.8.0 b2 (2005/05/22) Features added - Made WebDAV server distinguishable from the default HTTP server both in the ZMI and in event.log. - Included BTreeFolder2 Bugs fixed - Collector #1507/1728: Server addresses are now handled the same way on all platforms. This fixes the default binding on Windows. - Collector #1781: made 'create_mount_points' ZConfig option actually work (thanks to Dieter Maurer for the patch). - Collector #1780: DateTime.strftime() now handles dates <= 1900 or >= 2038 - Collector #1775: turning off debug mode by default - Collector #1784: fixed handling of multiple attributes in ZCTextIndex - Don't copy '.svn' directories from skeleton into an instance (thanks to Dale Hirt for the patch). - Collector #1776: Improved setup.py. The Finder class is now used for the complete lib/python tree and has a blacklist instead of a whitelist for file extensions. So there should no longer be a need to update setup.py if modules or files are added or removed in lib/python. - Collector #1751: Improved error reporting reporting during the startup phase - Collector #1745: Fixed ZSQL error KeyError 'query' - Collector #1735: fixed UnicodeDecodeError in Loader.py Zope 2.8b1 (2005/04/24) Features added - Added lazy: TAL expression and fixed defer: expression for python expression - ZCatalog.CatalogBrains: An _unrestrictedGetObject method has been added. - ZODB transactions now support savepoints. See transaction/savepoint.txt. These will replace subtransactions. Bugs fixed - Collector #1754: Fixed import of 'transaction' in 'zopectl adduser' (which wasy dying with a NameError). - Collector #1750: StructuredText: fixed handling of image URLs with query string - Collector #1748: Fixed SIGSEGV in Acquisition - Hotfix_20050405: classes defined in untrusted code could shadow the roles of methods defined as protected by their bases. - Collector #1656: Fixed enumeration within untrusted code (forward-port from 2.7 branch). - Collector #1721: Fixed handling of an empty indexed_attrs parameter Zope 2.8a2 (2005/04/02) Features added - ZCatalog.CatalogBrains: 'getObject' now raises errors, rather than returning None, in cases where the path points either to a nonexistent object (in which case it raises NotFound) or to one which the user cannot access (raising Unauthorized). Sites which rely on the old behavior can restore setting a new zope.conf option, 'catalog-getObject-raises', to "off". This compatibility option will be removed in Zope 2.10. - PluginIndexes: the ZCatalog's "Indexes" tab now show the number of distinct values indexed by each index instead of a mixture of indexed objects versus number of distinct values. Indexes derived from UnIndex show both values within their own ZMI screen. In addition most indexes have now a "Browse" tab to browse through the list of indexed values and their occurrences. - FTPServer: a RNFR (rename from) request is now being responded with a 550 error code if the source file does not exist - Fixed ObjectManager to not swallow exceptions during object deletion (in debug mode and if the user is not Manager). This allows for better debugging, while still keeping the possibility for a Manager to delete buggy objects. - Added a ZConfig directive 'large-file-threshold' to control the request content-size threshold at which a temporary file gets created. Use the same value for deciding between reading the whole request in memory or just a chunk inside webdav.NullResource.PUT(). - RAMCacheManager: Allow invalidation of a cache entry from the Statistics view in the ZMI - Collector #1454/OFS.File: Accept content types ending with "javascript" as editable through the File edit form, just like text/ types - Zope X3 3.0.0's 'src/zope' package is included now. - Five (Zope 3 integration technology for Zope 2) is included now in Products/Five. Bugs fixed - Collector #1460: guarded_apply was too restrictive. - OFS.Traversable still used a string 'NotFound' exception. - ZPublisher would fail to recognize a XML-RPC request if the content-type header included a 'charset' parameter. - Forward-ported 'aq_acquire'-related fix and associated tests from Zope 2.7.4. - Collector #1730: XML page templates couldn't call aq_parent in path expressions. - Fixed brain.getObject() to correctly traverse to an object even if one of its parents is not accessible, to be close to what the Publisher does. - Forward ported fix for OFS.CopySupport tests which corrected signature of a faux security policy's 'validate' method. - 'setup.py' did not install the 'Zope' compatibility module (the old 'Zope' package has been renamed to 'Zope2'). - Fixed Shared.DC.ZRDB.Results to behave with the new-style ExtensionClass. Added a test. - 'setup.py' did not install the new 'Zope' compatibility module (the 'Zope' package has been renamedd to 'Zope2'). - Collector #1507: Zope now binds again to all available IP addresses if ip-address is unset - Use 'del' instead of 'list.remove()' in Catalog.delColumn(). There can be only one column with the same name, and it could potentially break catalog metadata as remove() may remove more than one element from the list if they have the same value. Also, we already have the list index we are interested in deleting so it doesn't make sense to look up the value and call 'list.remove()' on it. - Collector #1628: FTP server has been broken (directory listings did not work) - Collector #1705: CopySource._postCopy is never called - Collector #1617: Fixed crash in ZPT code (caused by improper checks in cAccessControl) - Collector #1683: fixing batching in the DA "Test" tab - Collector #1648: Fix bug in Medusa FTP - Collector #1667: allow 'max-number-of-session-objects 0' to have the same effect as setting the value via the web interface (i.e., make the number of session objects unlimited, rather than falling back to the default). - Collector: #1651: removed compiler warning - Collector #1661: make 'python-check-interval' setting in zope.conf actually work as documented. This setting allows for important tuning opportunities for production Zope servers. - Collector #1657: Don't break host-based virtual hosting when purging an HTTP accelerator. - DTML Methods were not interoperable with the new filestream_iterator and caches based on it (FileCacheManager). - Collector #1655: fixed severe memory leak in TemporaryStorage - Collector #1407: fixed XML escaping problem introduced in 2.7.4 b1 - Collector #1151: HTTP compression was broken on error pages - The REQUEST now contains a new entry ACTUAL_URL which contains the full URL without query string as it appears within the location bar of the browser. The key has been added to provide a single key that is available for vhosted and non-vhosted installations. - Collector #1605: VHM did not quote URLs - webdav.Resource: during COPY, manage_afterClone was called way too early, thus the object wasn't bound to the database and couldn't find a context. Changed to behave the same way as CopySupport. - RAMCacheManager: opimized performance by using cPickle instead of pickle and by using the highest pickle protocol available instead of using ASCII pickles (patch by Dieter Maurer) - Collector #631: Image URLs in StructuredText containing port numbers were not rendered correctly - Collector #1498: Don't choke on malformed cookies. Cookies of the form "foo=bar; hmm; baz=gee" will give an empty value for 'hmm' instead of silently discarding it and the rest of the string. (Thanks to 'sirilyan' for the patch.) - bin/zopectl test now uses os.execv, instead os os.system, so that options with characters that needs shell quoting doesn't break the command. - Collector #1219: Make XML export sane again. - Collector #945: Allow adding empty PythonScript instances programmatically. - Updated doc/UNITTEST.txt and lib/python/Testing/README.txt to reflect progress made since UNITTEST.txt was originally written. - Removed Version objects from the add menu. Versions are agreed to be a feature that should not be used as it is not well implemented and allows for data loss. - Collector #1510: Allow encoding of application/xhtml+xml pages according to the charset specified in the Content-Type header (thanks to Jacek Konieczny for the patch). - Collector #1599: made sqltest work with unicode strings (thanks to Peter Sabaini for the patch). - zopectl: fixed handling of child processes (patch by Dieter Maurer) - Collector #1593: fixed dumb _get_id() implementation in OFS.CopySupport that produced copy_of_copy_of....files (thanks to Alexandre Boeglin for the patch). - Collector #1450: files in utilities/ZODBTools are now installed during the installation process in the 'bin' directory - Collector #1003: added new 'http-header-max-length' directive to zope.conf to specific the maximum length of a HTTP request header before it is considered as a possible DoS attack and discarded. - Collector #1371: added new 'cgi-maxlen' directive to zope.conf to limit the amount of form data being processed by Zope to prevent DoS attacks - Collector #1407: changed WebDAV display name for objects to title_or_id() - the 'trusted-proxy' directive in zope.conf now also accepts hostnames instead of IP addresses only (patch by Dieter Maurer) - Fixed test.py to not over-resolve symbolic links. Needed to run tests when the Products directory and a product are symlinks. - Collector #1583/ZReST: Fixed handling of the title attribute for non-ascii characters. - Collector #1577: Fixed cryptic error message in ZPublisher if a non-ASCII string is passed to a date, int, long or float property. - Collector #1576: Fixed Z Search Interface to use proper HTML. - Collector #1127: strftime did not take timezone into account. - Collector #1569/DateTime: Added a new ISO8601-method that will return correctly formatted ISO 8601-representations to augment the ISO method which isn't compliant with ISO 8601. - ZPublisher: changed some hardcoded 'latin1' arguments to 'iso-8859-15' since latin1 is obsolete. - Collector #1566: Installation of Zope on some older Solaris versions could fail due to a broken "echo" implementation causing the creation of a borked version.txt file. - Collector #934: Image and File objects are now always internally split into small chunks even when initialized from a string. - docutils: updated to V 0.3.5. The Zope core now contains a full copy of the docutils package except some GPLed files which can not be included with the Zope distribution due to license constraints on svn.zope.org. - docutils: moved from lib/python/docutils to lib/python/third_party/docutils - Collector #1557/OFS.Image: Introducing new 'alt' property. The 'alt' attribute is no longer taken from the 'title' property but from the new 'alt' property. The border="0" attribute is no longer part of the HTML output except specified otherwise. - Set a default value of '' for the new 'alt' property as not to break existing content. - Collector #1511: made IPCServer show up in the Control Panel under "Network Services" - Collector #1443: Applied patch by Simon Eisenmann that reimplements the XML parser used in WebDAV fixing a memory leak. - Always unescape element contents on webdav.xmltools - Use saxutils to escape/unescape values for/from PROPFIND/PROPPATCH. - Make OFS.PropertySheet use the escaping function from webdav.xmltools. - Escape/unescape " and ' - Don't escape properties stored as XML (ie: having a __xml_attrs__ metadata set by PROPPATCH) when building a PROPFIND response. - If a PROPPATCH element value contains only a CDATA section, store the CDATA contents only. - Catch AttributeErrors and KeyErrors raised from __bobo_traverse__ and convert them to NotFound. In debug mode a more verbose error message is issued, the same way it's done on attribute/item traversal. - Collector #1523: replace the text field for importing .zexp/.xml files with a selection list - Stitch newly-created object into it's container *before* calling it's PUT() method. This fixes an issue with OFS.File/OFS.Image that would result into reading the whole file in memory and wrapping it into a *single* Pdata object. - Import ZServer.CONNECTION_LIMIT variable *inside* the method that uses it. Before this, the variable was imported at the module level, thus binding it too early which would cause the ZConfig handler to have no real effect. Zope 2.8a1 (2004/10/17) Features added - Included Stefan Holek's ZopeTestCase 0.9 - The SiteErrorLog allows you to acknowledge (or delete) exceptions, so you can reduce or clear the list without restarting your Zope server. Additionally the SiteErrorLog is covered by unit tests now. - Unit tests added for the SiteErrorLog. - UI improvement for the ZCatalog. The "catalog contents" allow you to filter the cataloged objects by path now. - Made test.py follow symbolic links on POSIX systems. - added utilities/reindex_catalog.py to perform ZCatalog maintenance operations from the command line (through zopectl) - RESPONSE.setBody and RESPONSE.setStatus now accept lock parameters in the same way as RESPONSE.redirect. These prevent further calls to the methods from overwriting the previous value. This is useful when writing http proxies. - DateTime: new DateTime instance can be constructed from a given DateTime instance: d_new = DateTime(d_old) - The DateTime parser now throws a SyntaxError upon any parsing errors. - ZCatalog: added a new configuration option in the "Advanced" tab to provide optional logging of the progress of long running reindexing or recataloging operations. - made Zope.configure return the starter instance to enable other methods to be called, such as starter.setupConfiguredLoggers() - Improved Unicode handling in Page Templates. Template contents and title will now be saved as a Unicode string if the management_page_charset variable can be acquired and is true. The character set of an uploaded file can now be specified. - zopectl now accepts the -m argument to set a umask for files created by the managed process (e.g. -m 002 or --umask 002). - AccessControl/permission_settings() now has a new optional parameter 'permission' to retrieve the permission settings for a particular permission. - The obsolete 'SearchIndex' package has been removed - Traversal now supports a "post traversal hook" that get's run after traversal finished and the security context is established. - Using "_usage" parameters in a ZCatalog query is deprecated and logged as DeprecationWarning. - MailHost now has two additional properties, a user id and a password. These are used to attempt ESMTP authentication before sending a mail. - Folder listings in FTP now include "." as well as "..". - When a VHM is activated, it adds the mapping 'VIRTUAL_URL_PARTS': (SERVER_URL, BASEPATH1, virtual_url_path) to the request's 'other' dictionary. If BASEPATH1 is empty, it is omitted from the tuple. The joined parts are also added under the key 'VIRTUAL_URL'. Since the parts are evaluated before traversal continues, they will not reflect modifications to the path during traversal or by the addition of a default method such as 'index_html'. - Extension Classes, a key Zope foundation, have been totally rewritten based on Python new-style classes. This change provides a number of advantages: o Use of new-style class features (e.g. slots, descriptors, etc.) in Zope objects. Support for object protocols (special __ methods) added since Python 1.4. o Support for cyclic garbage collection. o Ability to use new-style classes as base classes of Zope objects. o Pave the way for sharing code between Zope 2 and Zope 3. Note -- Extension classes with __of__ methods are made into Python read descriptors. If an extension classes is used to implement a descriptor, indirectly by implementing __of__ or directly by implementing __get__, the behavior of the descriptor will differ from ordinary descriptors in an important way. The descriptors __get__ method will be called *even if* the descriptor is stored on an instance of an extension class. Normally descritor __get__ methods are called only of the descriptor is stored in a class. - ZODB 3.3 This is the first version of ZODB that does not require ExtensionClass. - Add 'parity' method to ZTUtils Iterators. - Allow untrusted code to mutate ZPublisher record objects. - Added a "mime-types" configuration value which names a file giving additional MIME type to filename extension mappings. The "mime-types" setting may be given more than once in the configuration file; the files have the same format at the mime.types file distributed with Apache. - Changed the ZEO server and control process to work with a single configuration file; this is now the default way to configure these processes. (It's still possible to use separate configuration files.) The ZEO configuration file can now include a "runner" section used by the control process and ignored by the ZEO server process itself. If present, the control process can use the same configuration file. - ZConfig was updated to version 2.0. The new version includes two new ways to perform schema extension; of particular interest in Zope is the ability for a configuration file to "import" new schema components to allow 3rd-party components (such as storages, databases, or logging handlers) to be used. - The testrunner.py script has been replaced with test.py which is now installed into the 'bin' folder. Bugs fixed - Removed Python 2.3.3 as valid option. ZODB 3.3 requires Python 2.3.4 or later. - Collector #1332: Added in-place migration of the Catalog.__len__ attribute to avoid new-style class caching problems. Instances of ZCatalog or instances of classes with ZCatalog as base class will be migrated automatically. Instances of Catalog or classes with Catalog as base class must be migrated manually by calling the migrate__len__() method on the every instance. In addition old BTree migration code (for pre-Zope 2.5 instances) has been removed. If you want to migrate from such an old version to Zope 2.8, you need to clear and reindex your ZCatalog). - Collector #1595: same as in Collector #1132 for indexes derived from UnIndex. Exisiting ZCatalog instances must be converted manually by calling the "manage_convertIndexes" method through-the-web for every single ZCatalog instance. See also doc/FAQ.txt (Installation, question #4) - Collector #1457: ZCTextIndex's QueryError and ParseError are now available for import from untrusted code. - Collector #1473: zpasswd.py can now accept --username without --password - Collector #1491: talgettext.py did not create a proper header for the generated .pot file if multiple pagetemplate files were processed. - Collector #1477: TaintedString.strip() now implements the same signature as str.strip() - TAL: tal:on-error does not trap ConflictError anymore. - OFS.CopySupport: Enforced "Delete objects" permission during move (CMF Collector #259). - Removed DWIM'y attempt to filter acquired-but-not-aceessible results from 'guarded_getattr'. - Collector #1267: applied patch to fix segmentation faults on x86_64 systems - ZReST: the charset used in the rendered HTML was not set to the corresponding output_encoding property of the ZReST instance. In addition changing the encodings through the Properties tab did not re-render the HTML. - Collector #1234: an exception triple passed to LOG() was not propagated properly to the logging module of Python - Collector #1441: Removed headers introduced to make Microsoft webfolders and office apps happy, since they make a lot of standards-compliant things unhappy AND they trick MS Office into trying to edit office files stored in Zope via WebDAV even when the user isn't allowed to edit them and is only trying to download them. - Collector #1445: Fixed bad interaction between -p and -v(v) options to test.py that resulted in exceptions being printed when they shouldn't have been. - Collector #729: manage_main doesn't display the correct page title most of the time. It is not completely fixed but using title_or_id makes folders display the correct id as a fallback. - Collector #1370: Fixed html generated by Z Search interface. - Collector #1295: Fixed minor niglet with the Elvis tutorial. - added "version.txt" to setup.py to avoid untrue "unreleased version" messages within the control panel - Collector #1436: applied patch to fix a memory leak in cAccessControl. - Collector #1431: fixed NetBSD support in initgroups.c - Collector #1406: fixed segmentation fault by acquisition - Collector #1392: ExternalMethod ignored management_page_charset - unrestrictedTraverse() refactored to remove hasattr calls (which mask conflict errors) and for greater readability and maintainability. - Zope can now be embedded in C/C++ without exceptions being raised in zdoptions. - Collector #1213: Fixed wrong labels of cache parameters - Collector #1265: Fixed handling of orphans in ZTUtil.Batch - Collector #1293: missing 'address' parameters within one of the server sections raise an exception. - Collector #1345: AcceleratedHTTPCacheManager now sends the Last-Modified header. - Collector #1126: ZPublisher.Converters.field2lines now using splitlines() instead of split('\n'). - Collector #1322: fixed HTML quoting problem with ZSQL methods in DA.py - Collector #1124: The ZReST product now uses the same reST encoding parameters from zope.conf as the low-level reStructuredText implementation. - Collector #1259: removed the "uninstall" target from the Makefile since the uninstall routine could also remove non-Zope files. Because this was to dangerous it has been removed completely. - Collector #1299: Fixed bug in sequence.sort() - Collector #1159: Added test for __MACH__ to initgroups.c so the initgroups method becomes available on Mac OS X. - Collector #1004: text,token properties were missing in PropertyManager management page. - Display index name on error message when index can't be used as 'sort_on'. - PUT would fail if the created object had a __len__ = 0 (eg: BTreeFolder2) and fallback to _default_put_factory. Fix by checking if the returned object is None instead. - Collector #1160: HTTPResponse.expireCookie() potentially didn't when an 'expires' keyword argument was passed. - Collector #1289: Allow ZSQL methods to be edited via WebDAV. - WebDAV property values were not being properly escaped on 'propstat'. - WebDAV 'supportedlock' was not checking if the object did implement the WriteLockInterface before returning it's value. - reStructuredText ignored the encoding settings in zope.conf - ObjectManager no longer raises string exceptions - Collector #1260: Testing/__init__.py no longer changes the INSTANCE_HOME. - App.config.setConfiguration() did not update the legacy source for debug_mode, Globals.DevelopmentMode. - Script (Python) objects now have a _filepath attribute, also used as the '__file__' global at runtime. This prevents an import problem caused by the fix to #1074. - Minor usability tweaks: * Increased FindSupport meta type selection widgets height to 8 lines - The DateTime module did not recognize the settings for "datetime-format". - Stop testrunner.py from recursing into the 'build-base' directory created by setup.py. - Collector #1074: Change Scripts' __name__ to None - Range searches with KeywordIndexes did not work with record-style query parameters - Item_w__name__ now has a working getId() method - PageTemplateFile now using Item_w__name__ mixin, fixing its getId() and absolute_url() methods. - Only one VirtualHostMonster is allowed per container. - Collector #1133: TreeTag choked on Ids of type long. - Collector #1012: A carefully crafted compressed tree state could violate size limit. Limit is no longer hardcoded. - Collector #1139: tal:attributes didn't escape double quotes. - Management interface of TopicIndexes has been completely broken - Collector #1129: Improper parsing of ISO8601 in DateTime. - Removed pervasive use of string exceptions (some may still be hiding in the woodwork, but all raise's with string literals are gone). - AccessControl.User used a misleading string exeception, 'NotImplemented', which shadowed the Python builtin. - Collector #426: Inconsistent, undocumented error() method. - Collector #799: Eliminate improper uses of SCRIPT_NAME. - Collector #445: Add internal global declaration for Script bindings. - Collector #616: Make CONTEXTS available to TALES Python expressions. - Collector #1074: Give Script execution context a __name__ - Collector #1095: Allow TAL paths starting with '/varname' as a preferred spelling for 'CONTEXTS/varname'. - Collector #391: Cut and paste now requires delete permissions. - Collector #331: Referenses to URL in manage_tabs was changed to REQUEST.URL to prevent accidental overriding. - Made the control panel properly reflect the cache-size setting of ZODB's object cache once again. - ConflictError was swallowed in ObjectManager by manage_beforeDelete and _delObject. This could break code expecting to do cleanups before deletion. - Python 2.3 BooleanType wasn't handled properly by ZTUtils marshalling and ZPublisher's converters. - Collector #1065: bin/ scripts didn't export HOME envars. - Collector #572: WebDAV GET protected by 'FTP Access' permission. Two new methods have been added to WebDAV resources, "manage_DAVget" and "listDAVObjects". These are now used by WebDAV instead of the earlier "manage_FTPget" and "objectValues". This separates the permissions, and allows WebDAV specific overriding of these methods. - Collector #904: Platform specific signals in zdaemon/Daemon.py (fixed by removing the "fossil" module from 2.7 branch and head). - Workaround for Collector #1081: The 'title' property for objects derived from OFS.Folder or PropertyManager can now be removed and replaced with a ustring property. This allows the usage of non-ISO-8859-1 or ASCII charsets - Collector #951: DateTime(None) is now equal to DateTime() - Collector #1056: aq_acquire() ignored the default argument - Collector #1087: ZPT: "repeat/item/length" did not work as documented in the Zope Book. - Collector #721: Entities in tal:attribute values weren't properly escaped. - Collector #851: Traversable.py: A bare try..except shadowed conflict errors - Collector #1058: Several fixes for PropertySheets when used outside ZClasses - Collector #1053: parseIndexRequest turned empty sequence of search terms into unrestricted search. - manage_tabs had a namespace problem with the acquisition of names from the manage_options variable resulting to acquire "target" and "action" from objects above in the hierachy. - PathIndex and TopicIndex are now using a counter for the number of indexed objects instead of using a very expensive calculation based on the keys of their indexes. - Collector #1039: Whitespace problem in Z2.log fixed - changed some bare try: except:'s in Shared.DC.ZRDB.Connection so that they now log exceptions that occur. - ObjectManager will now attempt to set Owner local role keyed to the user's id, rather than username. Zope-2.9.4-retire_zpkg/doc/INSTALL.txt0000644000175000017500000001632110351722412017306 0ustar tseavertseaverBuilding and installing Zope from source ---------------------------------------- Welcome to Zope! This document describes building and installing Zope on UNIX and Linux. See WINDOWS.txt for information about Windows. See the PLATFORMS directory for notes about various other platforms. System requirements when building from source * bash or another Bourne shell variant * Python 2.4.2 or later installed somewhere in the system PATH * GNU make * A C compiler (gcc recommended) Recommendations - You are recommended to build and install Zope as a non-root user. Building Zope To build Zope, run the conventional UNIX build sequence from within the Zope source tree:: ./configure --prefix=/where/to/install/zope make If you do not specify a '--prefix' option, during a later step, Zope will be installed into a default location. If the configure script cannot find a suitable Python interpreter for use with Zope, it will complain with an informative error message. If this happens, you may use the '--with-python' command-line option to 'configure' to specify which Python interpreter to use. Run './configure --help' to see other command-line options available via the configure script. Optional: Building and Installing Zope 'In-Place' (SVN checkouts only) Older versions of Zope were typically run directly from the 'source' directory itself. This is useful for development purposes. You can regain that behavior by performing the following sequence of commands within a Zope source directory: ./configure make instance This command also creates an administrative user with the specified username and password. WARNING: "make instance" doesn't work on FreeBSD 5.0 and presumably other platforms. You should either use GNU make (gmake instance), or use "make install" instead. Making an "In-Place" instance builds the binary files and creates the files necessary for a Zope instance to be run directly within the build directory (e.g. 'in-place'). You may start Zope by running:: ./bin/zopectl start See ./log/event.log for any output which may happen during start of Zope. If anything goes wrong you will see there. If you use ./bin/zopectl fg instead, the output is generated to the screen. In this case Zope does not detach from terminal. Optional: Building Zope Using The "Clean-Source-Tree" Method You can run the 'configure' command from outside of the Zope source tree. If you do so, the makefile will be written to your current directory. The files generated by the build process (via 'make') will be written to the directory from which you run 'configure'. You can then use 'make install' to install these files to their canonical locations. This feature is to support source locations which are not writable. Installing Zope To install Zope to the place you've specified via the '--prefix' option (or to the default location if you didn't specify a prefix), type:: make install Creating a Zope Instance Home Once you've performed the install step, to begin actually using Zope, you will need to create an "instance home", which is a directory that contains configuration and data for a Zope server process. The instance home is created using the 'mkzopeinstance.py' script:: /where/to/install/zope/bin/mkzopeinstance.py You will be asked to provide a user name and password for an administrator's account during 'mkzopeinstance'. Command-line options to 'mkzopeinstance' are available, and can be investigated by running 'mkzopeinstance.py --help'. Starting Zope Once an instance home has been created, the Zope server can now be started using this command: /location/of/zope/instance/bin/zopectl start During start, zope emits log messages into ./log/event.log You can examine it with the usual tools (cat, more, tail) and see if there are any errors preventing zope from starting. /location/of/zope/instance/bin/zopectl fg can be used to instead output these messages to the console. This way zope does not detach from terminal. If you get errors indicating that addresses are in use, then you will have to supply arguments to runzope to change the ports used for HTTP or FTP. The default HTTP and FTP ports used by Zope are 8080 and 8021 respectively. You can change the ports used by editing ./etc/zope.conf apropriately. The section usually is like this: # valid keys are "address" and "force-connection-close" address 8080 # force-connection-close on address can just be a port number as shown, but also a host:port pair to bind to a specific interface only. zopectl can be linked as rc-script in the usual start directories on linux or other system V unix variants. You can use zopectl interactively as a command shell by just calling it w/o any arguments. Try help there and help to find out about additionally commands of zopectl. These commands work also on command line. By default, 'zopectl start' will start a background process that manages Zope and 'zopectl stop' will stop the background process. Logging In To Zope Once you've started Zope, you can then connect to the Zope webserver by directing your browser to:: http://yourhost:8080/manage .. where 'yourhost' is the DNS name or IP address of the machine running Zope. If you changed the HTTP port as described, use a port number of 8080 + the port-base value. You will be prompted for a user name and password. Use the user name and password you provided in response to the prompts issued during the "make instance" process. Now you're off and running! You should be looking at the Zope management screen which is divided into two frames. On the left you can navigate between Zope objects and on the right you can edit them by selecting different management functions with the tabs at the top of the frame. If you haven't used Zope before, you should head to the Zope web site and read some documentation. The Zope Book is a good place to start. You can access the Zope Book at: http://www.zope.org/Documentation/Books/ZopeBook Integrating Zope With An Existing Webserver Zope doesn't require any existing webserver to run, but you can integrate it with other webservers as necessary. See the WEBSERVER.txt file for more information about configuring Zope with an existing web server. There is also information about integrating Zope with existing webservers on the Zope.org website. Troubleshooting - This version of Zope requires Python 2.4.1 or better. - The Python you run Zope with *must* have threads compiled in, which is the case for a vanilla build. Warning: Zope will not run with a Python version that uses libpth. You *must* use libpthread. - To build Python extensions you need to have Python configuration information available. If your Python comes from an RPM you may need the python-devel (or python-dev) package installed too. If you built Python from source all the configuration information should already be available. - See CHANGES.txt for important notes on this version of Zope. Zope-2.9.4-retire_zpkg/doc/TODO.txt0000644000175000017500000002060710050234363016746 0ustar tseavertseaverThe following is a TODO list dealing with installation and startup changes proposed for the Zope trunk. It is organized into these categories: "BEFORE 2.7 FINAL" (things that need to be done before we're finished, but not currently on the critical path) "MAYBE NEVER BUT NICE TO HAVE" (items that are not on any critical path) "COMMUNITY CONCERNS" (uncategorized concerns dealing with features missing from HEAD and prior 2.7 releases) ---------------------------------- BEFORE RELEASE OF ZOPE 2.7 FINAL ---------------------------------- Provide more intuitive command line option overrides Currently, you can override config file options by using the -X command line switch to runzope.py, followed by key/value pairs separated by an equal sign. This isn't explained anywhere and I'm not sure what limitations it has (can you change any value in the config file this way?). Zope-specific command-line options that don't require the -X (e.g. --event-log-file=something) should be provided to the user via changes to Zope/Startup/options/ZopeOptions. Make 'runzope -h' work and give better error messages when a configuration fails to make the grade. Currently runzope -h just emits a traceback, and the message printed by run.py says to run 'run.py -h' which can't work because things that it needs to import aren't on the PYTHONPATH. Config file needs better inline docs The Zope ZConfig config file has some inline docs. They need to be completed. Additional docs may come as a result of writing a schema-to-HTML translator. Make as many things defaultable as feasible Maybe we can allow a config file in which everything is commented out. We'll see. Write some more unit tests Write unit tests for Zope.Startup packages. What to do about envvars? Envvars are still used "under the hood" in ZConfig handlers as the result of particular configuration declarations in order to make Zope do the right thing (e.g. INSTANCE_HOME, SOFTWARE_HOME, DTML_REQUEST_AUTOQUOTE, SESSION_TIMEOUT_MINUTES and other envvars are set in ZConfig handlers for their respective keys). But envvars should not be used to try to configure Zope, as the handlers overwrite existing envvars with prejudice. We need to come down on one side or the other about envvars.. either they should be respected at startup as they always have been or they should be explicitly not respected. Currently they are not respected. We need to communicate this decision to developers and update doc/ENVIRONMENT.txt as necessary. win32-eventlog needs testing The "win32-eventlog" log handler (which is creatable via the config file) needs to be tested. Note: As of Jul 6, 2003, it has been confirmed to not work. The service name that it is logging under ("Zope") is not registered with the NT event service properly, causing a warning to be written to the log every time a log call is made. Server construction errors need to be better When a server is constructed, it attempts to bind to a port. If the port cannot be bound, an error is raised. The error currently doesn't include the port number, and should. I propose that we add two more options to the config file: Create import-directory and extensions-directory directives These would both be multikeys which specify some number of directories that contained importable zexp files and external methods, respectively. This would allow us to not require any fixed instance home directory. Instead, each path required by each subsystem is specifiable by itself in the config file. I'm sure that utilizing these options in the config file will break things that rely on having a monolithic INSTANCE_HOME such as products that attempt to do something like "import_dir = os.path.join(INSTANCE_HOME, 'import'). So I propose that the stock Zope instance home install continue to follow the old pattern (where everything is installed into a single instance home directory), but we provide the advanced config file options for roll-your-own packagers and advanced users. I would like to do the same thing for the software home, but I haven't thought much about it yet. Review the Zope Book 2.6 Edition chapters and come up with revisions or at least create a Zope 2.7 Install HowTo The 2.6 edition Zope Book at http://www.zope.org/Documentation/Books/ZopeBook/2_6Edition has three chapters which detail installation (Installing and Starting Zope), maintenance (Maintaining Zope) and ZEO (Scalability and ZEO). These chapters should be reviewed for inaccuracies with respect to the forthcoming trunk changes and changes should be made "offline" to allow a Zope Book 2.7 edition. At least create a HowTo which summarizes the differences between installing 2.6 and installing 2.7. ------------------------------ MAYBE NEVER BUT NICE TO HAVE ------------------------------ ZConfig defaults We deferred several issues that we recognized as areas for improvement in ZConfig that might make it possible to avoid writing nasty procedural code for default handling unnecessary (e.g. Zope.Startup.handlers.root_handler). See http://my.zope.com/CPM/CPM/issues/4 and http://my.zope.com/CPM/CPM/issues/3. Not necessary for merge, but useful to think about for future. ZConfig should keep enough state to be able to reconstitute the textual representation of the configuration. It would be nice if ZConfig kept enough state to be able to reconstitute the configuration in textual representation (to aid GUI builders and to make it possible to have a meaningful 'zopectl showconfig' or somesuch). ---------------------------------- COMMUNITY CONCERNS (uncategorized) ---------------------------------- Status: Request for comment sent to the community: http://mail.zope.org/pipermail/zope-dev/2003-March/018999.html Lots of discussion! - ZConfig is too complex when compared with envvar parsing. - Somewhat unrelated, but the features of "debug mode" should be disentangled from one another and specifiable individually. - Need to support arbitrary storage types. - Provide --swhome and ---with-python switch to mkzopeinstance, which will allow folks to create an instance that points to particular (known) Python versions and software homes. XXX This doesn't make sense. mkzopeinstance is part of the software home; if you want to use a different one, use the mkzopeinstance from the software home you want to use. The same goes for the Python to use; that's "built-in" to a software home. Using a different Python doesn't make sense given that the software home includes compiled modules. AAA This is to service to-be-chrooted installs. - Explain how to set up and use a ZEO server using mkzeoinst included in 2.7's ZEO. (Use the installed bin/mkzeoinstance script; use --help for more information.) Richard Jones has done work to allow you to create a ZEO instance in a way similar to creating a Zope instance (yay!) after creating a software home. - Give ZConfig replacement access to the environment or shell somehow. For instance, some folks use the same 'start' script in all of their instances right now (under 2.6). The script does things based on the value of an envvar that can be used to distinguish the config values of the instance from other instances. We could allow for the same sort of behavior E.g.: %define HOSTNAME `hostname` (assuming `hostname` resolves to a hostname) lockfile-name /var/lock/$HOSTNAME-lockfile - Give installaler an option to put libs in a user-specifiable directory at software home installation time. - Give installer an option to put docs in a user-specifiable directory at software home installation time. - Make it possible to install Zope-related Python libraries to The site-packages of the Python used to invoke setup.py. - Offer to install software home 'bin' scripts into a directory separate from the software home 'bin' directory. - Allow for the installation of platform-dependent files (basically Python extensions) to be installed to a place separate than that of platform independent files (as requested by Luca DeVitis). - Upon failure of Windows service startup, it's possible for the reason for the failure to not be logged anywhere. This is because we carefully wait til late in the startup process to write logfiles so UNIX has a chance to setuid. This is unnecessary for Windows. Zope-2.9.4-retire_zpkg/doc/ZEO/0000755000175000017500000000000010447233670016102 5ustar tseavertseaverZope-2.9.4-retire_zpkg/doc/ZEO/cache.txt0000644000175000017500000000360210267540504017704 0ustar tseavertseaverZEO Client Cache The client cache provides a disk based cache for each ZEO client. The client cache allows reads to be done from local disk rather than by remote access to the storage server. The cache may be persistent or transient. If the cache is persistent, then the cache file is retained for use after process restarts. A non- persistent cache uses a temporary file. The client cache is managed in a single file, of the specified size. The life of the cache is as follows: - The cache file is opened (if it already exists), or created and set to the specified size. - Cache records are written to the cache file, as transactions commit locally, and as data are loaded from the server. - Writes are to "the current file position". This is a pointer that travels around the file, circularly. After a record is written, the pointer advances to just beyond it. Objects starting at the current file position are evicted, as needed, to make room for the next record written. A distinct index file is not created, although indexing structures are maintained in memory while a ClientStorage is running. When a persistent client cache file is reopened, these indexing structures are recreated by analyzing the file contents. Persistent cache files are created in the directory named in the ``var`` argument to the ClientStorage, or if ``var`` is None, in the current working directory. Persistent cache files have names of the form:: client-storage.zec where: client -- the client name, as given by the ClientStorage's ``client`` argument storage -- the storage name, as given by the ClientStorage's ``storage`` argument; this is typically a string denoting a small integer, "1" by default For example, the cache file for client '8881' and storage 'spam' is named "8881-spam.zec". Zope-2.9.4-retire_zpkg/doc/ZEO/README.txt0000644000175000017500000000106210050174114017562 0ustar tseavertseaverZEO Documentation ================= This directory contains ZEO documentation. howto.txt The first place to look. It provides a high-level overview of ZEO features and details on how to install and configure clients and servers. Includes a configuration reference. cache.txt Explains how the client cache works. trace.txt Describe cache trace tool used to determine ideal cache size. ZopeREADME.txt A somewhat dated description of how to integrate ZEO with Zope. It provides a few hints that are not yet in howto.txt. Zope-2.9.4-retire_zpkg/doc/ZEO/ZopeREADME.txt0000644000175000017500000000713010050174114020422 0ustar tseavertseaverZope Enterprise Objects (ZEO) Installation ZEO 2.0 requires Zope 2.4 or higher and Python 2.1 or higher. If you use Python 2.1, we recommend the latest minor release (2.1.3 as of this writing) because it includes a few bug fixes that affect ZEO. Put the package (the ZEO directory, without any wrapping directory included in a distribution) in your Zope lib/python. The setup.py script in the top-level ZEO directory can also be used. Run "python setup.py install --home=ZOPE" where ZOPE is the top-level Zope directory. You can test ZEO before installing it with the test script:: python test.py -v Run the script with the -h option for a full list of options. The ZEO 2.0b2 release contains 122 unit tests on Unix. Starting (and configuring) the ZEO Server To start the storage server, go to your Zope install directory and run:: python lib/python/ZEO/start.py -p port_number This run the storage sever under zdaemon. zdaemon automatically restarts programs that exit unexpectedly. The server and the client don't have to be on the same machine. If they are on the same machine, then you can use a Unix domain socket:: python lib/python/ZEO/start.py -U filename The start script provides a number of options not documented here. See doc/start.txt for more information. Running Zope as a ZEO client To get Zope to use the server, create a custom_zodb module, custom_zodb.py, in your Zope install directory, so that Zope uses a ClientStorage:: from ZEO.ClientStorage import ClientStorage Storage = ClientStorage(('', port_number)) You can specify a host name (rather than '') if you want. The port number is, of course, the port number used to start the storage server. You can also give the name of a Unix domain socket file:: from ZEO.ClientStorage import ClientStorage Storage = ClientStorage(filename) There are a number of configuration options available for the ClientStorage. See doc/ClientStorage.txt for details. If you want a persistent client cache which retains cache contents across ClientStorage restarts, you need to define the environment variable, ZEO_CLIENT, or set the client keyword argument to the constructor to a unique name for the client. This is needed so that unique cache name files can be computed. Otherwise, the client cache is stored in temporary files which are removed when the ClientStorage shuts down. For example, to start two Zope processes with unique caches, use something like:: python z2.py -P8700 ZEO_CLIENT=8700 python z2.py -P8800 ZEO_CLIENT=8800 Zope product installation Normally, Zope updates the Zope database during startup to reflect product changes or new products found. It makes no sense for multiple ZEO clients to do the same installation. Further, if different clients have different software installed, the correct state of the database is ambiguous. Zope will not modify the Zope database during product installation if the environment variable ZEO_CLIENT is set. Normally, Zope ZEO clients should be run with ZEO_CLIENT set so that product initialization is not performed. If you do install new Zope products, then you need to take a special step to cause the new products to be properly registered in the database. The easiest way to do this is to start Zope once with the environment variable FORCE_PRODUCT_LOAD set. The interaction between ZEO and Zope product installation is unfortunate. Zope-2.9.4-retire_zpkg/doc/ZEO/trace.txt0000644000175000017500000001661310271522377017750 0ustar tseavertseaverZEO Client Cache Tracing ======================== An important question for ZEO users is: how large should the ZEO client cache be? ZEO 2 (as of ZEO 2.0b2) has a new feature that lets you collect a trace of cache activity and tools to analyze this trace, enabling you to make an informed decision about the cache size. Don't confuse the ZEO client cache with the Zope object cache. The ZEO client cache is only used when an object is not in the Zope object cache; the ZEO client cache avoids roundtrips to the ZEO server. Enabling Cache Tracing ---------------------- To enable cache tracing, you must use a persistent cache (specify a ``client`` name), and set the environment variable ZEO_CACHE_TRACE to a non-empty value. The path to the trace file is derived from the path to the persistent cache file by appending ".trace". If the file doesn't exist, ZEO will try to create it. If the file does exist, it's opened for appending (previous trace information is not overwritten). If there are problems with the file, a warning message is logged. To start or stop tracing, the ZEO client process (typically a Zope application server) must be restarted. The trace file can grow pretty quickly; on a moderately loaded server, we observed it growing by 7 MB per hour. The file consists of binary records, each 34 bytes long if 8-byte oids are in use; a detailed description of the record lay-out is given in stats.py. No sensitive data is logged: data record sizes (but not data records), and binary object and transaction ids are logged, but no object pickles, object types or names, user names, transaction comments, access paths, or machine information (such as machine name or IP address) are logged. Analyzing a Cache Trace ----------------------- The stats.py command-line tool is the first-line tool to analyze a cache trace. Its default output consists of two parts: a one-line summary of essential statistics for each segment of 15 minutes, interspersed with lines indicating client restarts, followed by a more detailed summary of overall statistics. The most important statistic is the "hit rate", a percentage indicating how many requests to load an object could be satisfied from the cache. Hit rates around 70% are good. 90% is excellent. If you see a hit rate under 60% you can probably improve the cache performance (and hence your Zope application server's performance) by increasing the ZEO cache size. This is normally configured using key ``cache_size`` in the ``zeoclient`` section of your configuration file. The default cache size is 20 MB, which is small. The stats.py tool shows its command line syntax when invoked without arguments. The tracefile argument can be a gzipped file if it has a .gz extension. It will be read from stdin (assuming uncompressed data) if the tracefile argument is '-'. Simulating Different Cache Sizes -------------------------------- Based on a cache trace file, you can make a prediction of how well the cache might do with a different cache size. The simul.py tool runs a simulation of the ZEO client cache implementation based upon the events read from a trace file. A new simulation is started each time the trace file records a client restart event; if a trace file contains more than one restart event, a separate line is printed for each simulation, and a line with overall statistics is added at the end. Example, assuming the trace file is in /tmp/cachetrace.log:: $ python simul.py -s 4 /tmp/cachetrace.log CircularCacheSimulation, cache size 4,194,304 bytes START TIME DURATION LOADS HITS INVALS WRITES HITRATE EVICTS INUSE Jul 22 22:22 39:09 3218856 1429329 24046 41517 44.4% 40776 99.8 This shows that with a 4 MB cache size, the cache hit rate is 44.4%, the percentage 1429329 (number of cache hits) is of 3218856 (number of load requests). The cache simulated 40776 evictions, to make room for new object states. At the end, 99.8% of the bytes reserved for the cache file were in use to hold object state (the remaining 0.2% consists of "holes", bytes freed by object eviction and not yet reused to hold another object's state). Let's try this again with an 8 MB cache:: $ python simul.py -s 8 /tmp/cachetrace.log CircularCacheSimulation, cache size 8,388,608 bytes START TIME DURATION LOADS HITS INVALS WRITES HITRATE EVICTS INUSE Jul 22 22:22 39:09 3218856 2182722 31315 41517 67.8% 40016 100.0 That's a huge improvement in hit rate, which isn't surprising since these are very small cache sizes. The default cache size is 20 MB, which is still on the small side:: $ python simul.py /tmp/cachetrace.log CircularCacheSimulation, cache size 20,971,520 bytes START TIME DURATION LOADS HITS INVALS WRITES HITRATE EVICTS INUSE Jul 22 22:22 39:09 3218856 2982589 37922 41517 92.7% 37761 99.9 Again a very nice improvement in hit rate, and there's not a lot of room left for improvement. Let's try 100 MB:: $ python simul.py -s 100 /tmp/cachetrace.log CircularCacheSimulation, cache size 104,857,600 bytes START TIME DURATION LOADS HITS INVALS WRITES HITRATE EVICTS INUSE Jul 22 22:22 39:09 3218856 3218741 39572 41517 100.0% 22778 100.0 It's very unusual to see a hit rate so high. The application here frequently modified a very large BTree, so given enough cache space to hold the entire BTree it rarely needed to ask the ZEO server for data: this application reused the same objects over and over. More typical is that a substantial number of objects will be referenced only once. Whenever an object turns out to be loaded only once, it's a pure loss for the cache: the first (and only) load is a cache miss; storing the object evicts other objects, possibly causing more cache misses; and the object is never loaded again. If, for example, a third of the objects are loaded only once, it's quite possible for the theoretical maximum hit rate to be 67%, no matter how large the cache. The simul.py script also contains code to simulate different cache strategies. Since none of these are implemented, and only the default cache strategy's code has been updated to be aware of MVCC, these are not further documented here. Simulation Limitations ---------------------- The cache simulation is an approximation, and actual hit rate may be higher or lower than the simulated result. These are some factors that inhibit exact simulation: - The simulator doesn't try to emulate versions. If the trace file contains loads and stores of objects in versions, the simulator treats them as if they were loads and stores of non-version data. - Each time a load of an object O in the trace file was a cache hit, but the simulated cache has evicted O, the simulated cache has no way to repair its knowledge about O. This is more frequent when simulating caches smaller than the cache used to produce the trace file. When a real cache suffers a cache miss, it asks the ZEO server for the needed information about O, and saves O in the client cache. The simulated cache doesn't have a ZEO server to ask, and O continues to be absent in the simulated cache. Further requests for O will continue to be simulated cache misses, although in a real cache they'll likely be cache hits. On the other hand, the simulated cache doesn't need to evict any objects to make room for O, so it may enjoy further cache hits on objects a real cache would have evicted. Zope-2.9.4-retire_zpkg/doc/ZEO/howto.txt0000644000175000017500000004302110050174114017766 0ustar tseavertseaver========================== Running a ZEO Server HOWTO ========================== Introduction ------------ ZEO (Zope Enterprise Objects) is a client-server system for sharing a single storage among many clients. Normally, a ZODB storage can only be used by a single process. When you use ZEO, the storage is opened in the ZEO server process. Client programs connect to this process using a ZEO ClientStorage. ZEO provides a consistent view of the database to all clients. The ZEO client and server communicate using a custom RPC protocol layered on top of TCP. There are several configuration options that affect the behavior of a ZEO server. This section describes how a few of these features working. Subsequent sections describe how to configure every option. Client cache ~~~~~~~~~~~~ Each ZEO client keeps an on-disk cache of recently used objects to avoid fetching those objects from the server each time they are requested. It is usually faster to read the objects from disk than it is to fetch them over the network. The cache can also provide read-only copies of objects during server outages. The cache may be persistent or transient. If the cache is persistent, then the cache files are retained for use after process restarts. A non-persistent cache uses temporary files that are removed when the client storage is closed. The client cache size is configured when the ClientStorage is created. The default size is 20MB, but the right size depends entirely on the particular database. Setting the cache size too small can hurt performance, but in most cases making it too big just wastes disk space. The document "Client cache tracing" describes how to collect a cache trace that can be used to determine a good cache size. ZEO uses invalidations for cache consistency. Every time an object is modified, the server sends a message to each client informing it of the change. The client will discard the object from its cache when it receives an invalidation. These invalidations are often batched. Each time a client connects to a server, it must verify that its cache contents are still valid. (It did not receive any invalidation messages while it was disconnected.) There are several mechanisms used to perform cache verification. In the worst case, the client sends the server a list of all objects in its cache along with their timestamps; the server sends back an invalidation message for each stale object. The cost of verification is one drawback to making the cache too large. Note that every time a client crashes or disconnects, it must verify its cache. Every time a server crashes, all of its clients must verify their caches. The cache verification process is optimized in two ways to eliminate costs when restarting clients and servers. Each client keeps the timestamp of the last invalidation message it has seen. When it connects to the server, it checks to see if any invalidation messages were sent after that timestamp. If not, then the cache is up-to-date and no further verification occurs. The other optimization is the invalidation queue, described below. Invalidation queue ~~~~~~~~~~~~~~~~~~ The ZEO server keeps a queue of recent invalidation messages in memory. When a client connects to the server, it sends the timestamp of the most recent invalidation message it has received. If that message is still in the invalidation queue, then the server sends the client all the missing invalidations. This is often cheaper than perform full cache verification. The default size of the invalidation queue is 100. If the invalidation queue is larger, it will be more likely that a client that reconnects will be able to verify its cache using the queue. On the other hand, a large queue uses more memory on the server to store the message. Invalidation messages tend to be small, perhaps a few hundred bytes each on average; it depends on the number of objects modified by a transaction. Transaction timeouts ~~~~~~~~~~~~~~~~~~~~ A ZEO server can be configured to timeout a transaction if it takes too long to complete. Only a single transaction can commit at a time; so if one transaction takes too long, all other clients will be delayed waiting for it. In the extreme, a client can hang during the commit process. If the client hangs, the server will be unable to commit other transactions until it restarts. A well-behaved client will not hang, but the server can be configured with a transaction timeout to guard against bugs that cause a client to hang. If any transaction exceeds the timeout threshold, the client's connection to the server will be closed and the transaction aborted. Once the transaction is aborted, the server can start processing other client's requests. Most transactions should take very little time to commit. The timer begins for a transaction after all the data has been sent to the server. At this point, the cost of commit should be dominated by the cost of writing data to disk; it should be unusual for a commit to take longer than 1 second. A transaction timeout of 30 seconds should tolerate heavy load and slow communications between client and server, while guarding against hung servers. When a transaction times out, the client can be left in an awkward position. If the timeout occurs during the second phase of the two phase commit, the client will log a panic message. This should only cause problems if the client transaction involved multiple storages. If it did, it is possible that some storages committed the client changes and others did not. Monitor server ~~~~~~~~~~~~~~ The ZEO server updates several counters while it is running. It can be configured to run a separate monitor server that reports the counter values and other statistics. If a client connects to the socket, the server send a text report and close the socket immediately. It does not read any data from the client. An example of a monitor server report is included below:: ZEO monitor server version 2.1a1 Fri Apr 4 16:57:42 2003 Storage: 1 Server started: Fri Apr 4 16:57:37 2003 Clients: 0 Clients verifying: 0 Active transactions: 0 Commits: 0 Aborts: 0 Loads: 0 Stores: 0 Conflicts: 0 Conflicts resolved: 0 Connection management ~~~~~~~~~~~~~~~~~~~~~ A ZEO client manages its connection to the ZEO server. If it loses the connection, it starts a thread that attempts to reconnect. While it is disconnected, it can satisfy some reads by using its cache. The client can be configured to wait a connection when it is created or to return immediately and provide data from its persistent cache. It usually simplifies programming to have the client wait for a connection on startup. When the client is disconnected, it polls periodically to see if the server is available. The rate at which it polls is configurable. The client can be configured with multiple server addresses. In this case, it assumes that each server has identical content and will use any server that is available. It is possible to configure the client to accept a read-only connection to one of these servers if no read-write connection is available. If it has a read-only connection, it will continue to poll for a read-write connection. This feature supports the Zope Replication Services product, http://www.zope.com/Products/ZopeProducts/ZRS. In general, it could be used to with a system that arranges to provide hot backups of servers in the case of failure. Authentication ~~~~~~~~~~~~~~ ZEO supports optional authentication of client and server using a password scheme similar to HTTP digest authentication (RFC 2069). It is a simple challenge-response protocol that does not send passwords in the clear, but does not offer strong security. The RFC discusses many of the limitations of this kind of protocol. Note that this feature provides authentication only. It does not provide encryption or confidentiality. The challenge-response also produces a session key that is used to generate message authentication codes for each ZEO message. This should prevent session hijacking. Guard the password database as if it contained plaintext passwords. It stores the hash of a username and password. This does not expose the plaintext password, but it is sensitive nonetheless. An attacker with the hash can impersonate the real user. This is a limitation of the simple digest scheme. The authentication framework allows third-party developers to provide new authentication modules. Installing software ------------------- ZEO is distributed as part of the ZODB3 package and with Zope, starting with Zope 2.7. You can download it from: - http://www.zope.org/Products/ZODB3.2, or - http://www.zope.org/Products/Zope To use ZEO with Zope 2.6, download ZODB3.2 and install it into your Zope software home. ZODB3 comes with a distutils setup.py script. You can use the --home option to setup.py install to the software in custom location. For example, if Zope is installed in /home/zope, then this command will install the new ZEO and ZODB: python setup.py install --home /home/zope The install command should create a /home/zope/lib/python/ZEO directoy. Configuring server ------------------ The script runzeo.py runs the ZEO server. The server can be configured using command-line arguments or a config file. This document describes only describes the config file. Run runzeo.py -h to see the list of command-line arguments. The runzeo.py script imports the ZEO package. ZEO must either be installed in Python's site-packages directory or be in a directory on PYTHONPATH. The configuration file specifies the underlying storage the server uses, the address it binds, and a few other optional parameters. An example is:: address zeo.example.com:8090 monitor-address zeo.example.com:8091 path /var/tmp/Data.fs path /var/tmp/zeo.log format %(asctime)s %(message)s This file configures a server to use a FileStorage from /var/tmp/Data.fs. The server listens on port 8090 of zeo.example.com. It also starts a monitor server that lists in port 8091. The ZEO server writes its log file to /var/tmp/zeo.log and uses a custom format for each line. Assuming the example configuration it stored in zeo.config, you can run a server by typing:: python /usr/local/bin/runzeo.py -C zeo.config A configuration file consists of a section and a storage section, where the storage section can use any of the valid ZODB storage types. It may also contain an eventlog configuration. See the document "Configuring a ZODB database" for more information about configuring storages and eventlogs. The zeo section must list the address. All the other keys are optional. address The address at which the server should listen. This can be in the form 'host:port' to signify a TCP/IP connection or a pathname string to signify a Unix domain socket connection (at least one '/' is required). A hostname may be a DNS name or a dotted IP address. If the hostname is omitted, the platform's default behavior is used when binding the listening socket ('' is passed to socket.bind() as the hostname portion of the address). read-only Flag indicating whether the server should operate in read-only mode. Defaults to false. Note that even if the server is operating in writable mode, individual storages may still be read-only. But if the server is in read-only mode, no write operations are allowed, even if the storages are writable. Note that pack() is considered a read-only operation. invalidation-queue-size The storage server keeps a queue of the objects modified by the last N transactions, where N == invalidation_queue_size. This queue is used to speed client cache verification when a client disconnects for a short period of time. monitor-address The address at which the monitor server should listen. If specified, a monitor server is started. The monitor server provides server statistics in a simple text format. This can be in the form 'host:port' to signify a TCP/IP connection or a pathname string to signify a Unix domain socket connection (at least one '/' is required). A hostname may be a DNS name or a dotted IP address. If the hostname is omitted, the platform's default behavior is used when binding the listening socket ('' is passed to socket.bind() as the hostname portion of the address). transaction-timeout The maximum amount of time to wait for a transaction to commit after acquiring the storage lock, specified in seconds. If the transaction takes too long, the client connection will be closed and the transaction aborted. authentication-protocol The name of the protocol used for authentication. The only protocol provided with ZEO is "digest," but extensions may provide other protocols. authentication-database The path of the database containing authentication credentials. authentication-realm The authentication realm of the server. Some authentication schemes use a realm to identify the logic set of usernames that are accepted by this server. Configuring client ------------------ The ZEO client can also be configured using ZConfig. The ZODB.config module provides several function for opening a storage based on its configuration. - ZODB.config.storageFromString() - ZODB.config.storageFromFile() - ZODB.config.storageFromURL() The ZEO client configuration requires the server address be specified. Everything else is optional. An example configuration is:: server zeo.example.com:8090 To use a ZEO client from Zope, write a configuration file and load it from custom_zodb.py:: from ZODB.config import storageFromURL Storage = storageFromURL("/path/to/client.txt") The other configuration options are listed below. storage The name of the storage that the client wants to use. If the ZEO server serves more than one storage, the client selects the storage it wants to use by name. The default name is '1', which is also the default name for the ZEO server. cache-size The maximum size of the client cache, in bytes. name The storage name. If unspecified, the address of the server will be used as the name. client Enables persistent cache files. The string passed here is used to construct the cache filenames. If it is not specified, the client creates a temporary cache that will only be used by the current object. var The directory where persistent cache files are stored. By default cache files, if they are persistent, are stored in the current directory. min-disconnect-poll The minimum delay in seconds between attempts to connect to the server, in seconds. Defaults to 5 seconds. max-disconnect-poll The maximum delay in seconds between attempts to connect to the server, in seconds. Defaults to 300 seconds. wait A boolean indicating whether the constructor should wait for the client to connect to the server and verify the cache before returning. The default is true. read-only A flag indicating whether this should be a read-only storage, defaulting to false (i.e. writing is allowed by default). read-only-fallback A flag indicating whether a read-only remote storage should be acceptable as a fallback when no writable storages are available. Defaults to false. At most one of read_only and read_only_fallback should be true. realm The authentication realm of the server. Some authentication schemes use a realm to identify the logic set of usernames that are accepted by this server. A ZEO client can also be created by calling the ClientStorage constructor explicitly. For example:: from ZEO.ClientStorage import ClientStorage storage = ClientStorage(("zeo.example.com", 8090)) Running the ZEO server as a daemon ---------------------------------- In an operational setting, you will want to run the ZEO server a daemon process that is restarted when it dies. The zdaemon package provides two tools for running daemons: zdrun.py and zdctl.py. The document "Using zdctl and zdrun to manage server processes" (Doc/zdctl.txt) explains how to use these scripts to manage daemons. Rotating log files ~~~~~~~~~~~~~~~~~~ ZEO will re-initialize its logging subsystem when it receives a SIGUSR2 signal. If you are using the standard event logger, you should first rename the log file and then send the signal to the server. The server will continue writing to the renamed log file until it receives the signal. After it receives the signal, the server will create a new file with the old name and write to it. Tools ----- There are a few scripts that may help running a ZEO server. The zeopack.py script connects to a server and packs the storage. It can be run as a cron job. The zeoup.py script attempts to connect to a ZEO server and verify that is is functioning. The zeopasswd.py script manages a ZEO servers password database. Diagnosing problems ------------------- If an exception occurs on the server, the server will log a traceback and send an exception to the client. The traceback on the client will show a ZEO protocol library as the source of the error. If you need to diagnose the problem, you will have to look in the server log for the rest of the traceback. Zope-2.9.4-retire_zpkg/doc/SECURITY.txt0000644000175000017500000000676710050234363017463 0ustar tseavertseaverSetting the initial user name and password Because Zope is managed through the web, user names and passwords must be used to assure that only authorized people can make changes to a Zope installation. Some user name and password is needed to "bootstrap" the creation of normal managers of your Zope site. This is accomplished through the use of the file 'inituser'. The first time Zope starts, it will detect that no users have been defined in the root user folder. It will search for the 'inituser' file and, if it exists, will add the user defined in the file to the root user folder. Normally, 'inituser' is created by the Zope install scripts. Either the installer prompts for the password or a randomly generated password is created and displayed at the end of the build script. You can use the 'zpasswd.py' script to create 'inituser' yourself. Execute 'zpasswd.py' like this:: python zpasswd.py inituser The script will prompt you for the name, password, and allowed domains. The default is to encode the password with SHA, so please remember this password as there is no way to recover it (although 'zpasswd.py' lets you reset it.) In some situations you may need to bypass normal security controls because you have lost your password or because the security settings have been mixed up. Zope provides a facility called an "emergency user" so that you can reset passwords and correct security settings. The emergency user password must be defined outside the application user interface. It is defined in the 'access' file located in the Zope directory. It should be readable only by the user as which your web server runs. To create the emergency user, use 'zpasswd.py' to create the 'access' file like this:: python zpasswd.py access In order to provide a somewhat higher level of security, various encoding schemes are supported which provide access to either SHA-1 encryption or the standard UNIX crypt facility if it has been compiled into Python. Unless you have some special requirements (see below), you should use the SHA-1 facility, which is the default. Format of 'inituser' and 'access' A password file should consist of a single line of the form: name:password Note that you may also add an optional third component to the line in the access file to restrict access by domain. For example, the line: mario:nintendoRules:*.mydomain.com in your 'access' file will only allow permit emergency user access from *.mydomain.com machines. Attempts to access the system from other domains will fail, even if the correct emergency user name and password are used. Please note that if you use the ZServer monitor capability, you will need to run with a clear text password. Setting permissions on the var directory. You need to set permissions on the Zope var directory. Zope needs to read and write data from its var directory. Before running Zope you should ensure that you give adequate permissions to the Zope var directory for the userid Zope will run under. Depending on how you choose to run Zope you will need to give different permissions to the var directory. If you use Zope with an existing web server, it will probably run Zope as 'nobody'. In this case 'nobody' needs read and write permissions to the var directory. If you change the way you run Zope you may need to modify the permissions of the var directory and the files in it to allow Zope to read and write under its changed userid. Zope-2.9.4-retire_zpkg/doc/FAQ.txt0000644000175000017500000002624410347323375016626 0ustar tseavertseaverZope Installation Frequently Asked Questions -------------------------------------------- Installing Zope 1. On certain Unix platforms (usually Solaris) I get a "checksum error" untarring the Zope distribution. Whats the deal? Zope is built and distributed using GNU tar. Some vendor-supplied tar implementations have problems with long path names as they appear in GNU tar created files. This is a problem that occurs in a number of software distributions created using GNU tar, not just Zope. We suggest that you install a GNU tar on your system to avoid this problem (not just with Zope, but with other software distributions as well). 2. I am trying to build Zope on my BSD based system, but I keep getting "symbol not found" errors and the build scripts stop. What do I do? On some BSD based systems (BSDI, BSD/OS), you need to edit the Makefile.pre.in files in your Zope installation to add -rdynamic to the LDSHARED makefile variable. On some systems it may also be necessary to change the file named 'do.py' located in the 'inst' directory of your Zope installation, changing the line: do('make') to: do('make -k'). 3. I am having trouble building Zope on my OpenBSD system. I get some wierd compilation errors. Make sure you unpack Zope using GNU tar; you will not get any error messages with OpenBSD's standard tar, but your installation will be subtly broken due to problems with long path names. 4. I am having trouble building Zope on a libc 5 Linux machine. Zope requires Python be built with glibc 2.x (libc 6) on Linux. 5. I am trying to install Zope on a Windows NT/2000 machine, but I keep getting a dialog saying "corrupt installation detected". Is something wrong with the distribution file? No, to install Windows NT / 2000 you should be logged in with "Administrator" privileges on the machine. If you are seeing the "corrupt installation detected" dialog, you probably don't have the required administrator privileges (your guess is as good as ours as to why you get that particular error message). Starting/Accessing your Zope installation 1. After installing Zope, I go to the URL in my web browser but I get a "404 Not Found" or "Server Error" message Is the URL really correct? Are you running Zope behind another web server? If so, this message is coming from your web server, not Zope. It usually means that your web server is misconfigured. Look in the error log for your web server for details of the error. 2. I have installed Zope, and when I go to the URL in my web browser, I get a password prompt. Although I type in the correct username and password, I keep getting prompted. What is going on? Are you running another web server in front of Zope? Zope manages access control internally, but it relies on your web server software to relay any authentication information in web requests. Some web servers automatically filter this information out of requests passed to cgi programs. If you keep getting password prompts that never accept your password, this means that your web server is not properly configured to pass authentication info on to Zope. See the doc/WEBVSERVER.txt file for information on correctly configuring your web server to pass authentication information. 3. I have installed Zope, and when I go to the URL in my web browser, I get a "Connection refused" error. Probably this means that Zope has failed to start. You should try to start Zope in the foreground and look for error messages. On Linux / Unix / OSX, you can do this by giving the command "./bin/runzope" or "./bin/zopectl fg" in your zope instance (they are equivalent). On Windows, navigate to the Zope folder in your Start Menu and click on "Run Zope in Console". A console window with process startup information will be displayed. If there are errors, the last error shown should explain what went wrong. 4. When I go to a URL for an application that isn't running, it takes quite a while to startup. Why is that? The application has to get into memory and then get the database loaded. Depending on database file size, this might take a while. Packing your Zope database at regular intervals can reduce startup time. 5. I have Zope with the Oracle Database adapter installed, and can't get it running. Why? If you have Oracle installed, you need to ensure that the environment variable "ORACLE_HOME" is in the environment of the running application. You can do this by adding a line to the section of etc/zope.conf, such as: ORACLE_HOME /foo/bar/ 6. I have forgotten the only password used to access the site or I have modified the security settings in such a way that even I can't get access. How do I fix it? Assuming you have write access to the directory where Zope is installed, you can create a temporary "emergency user" using the 'zpasswd.py' script:: python bin/zpasswd.py access Follow the prompts to enter a user name and password. 'zpasswd.py' will write the file named 'access'. Zope will look for this file the next time it starts. After restarting, browse to Zope's management interface and use the name and password you entered. As the emergency user, you are allowed to create user folders and user accounts as well as adjust security settings but you are not allowed to create objects like DTML methods or folders. This is a safety precaution. See more details in the file SECURITY.TXT. Managing the Zope process 1. How do I find the application server in my process listing? When running Zope, there will be a .pid file in var/Z2.pid which contains two process IDs. 2. If I have more than one Zope process running on the same machine, how do I tell them apart in "ps" listings? When running under ZServer, the Zope processes will show up in the listings with 'run.py'. (You may need to do a long listing to see it.) Look for the pids listed in var/Z2.pid. 3. Is it OK to use 'kill' to shut down the process? If you started zope with the command "zopectl start", the command "zopectl stop" will shut down Zope. You can also shut down the process using the Shutdown button in the Control Panel. Alternatively, the URL: 'Control_Panel/manage_shutdown' will, with a suitable username and password, shutdown the application. If you need a non-interactive way to shutdown your application, e.g. from a script, then write a program that sends a web request to that URL with the appropriate username and password. If you must, you can shut down the application by killing it. The respective var/Z2.pid file will have the pids. Upgrading from Earlier Versions of Zope 1. How can I upgrade to Zope 2.8? The usual procedure when installing a new version of Zope is: - Create a new instance (see doc/INSTALL.txt). - Copy the var/Data.fs file from your old instance into your new instance's var/ directory. It is best to do this while the old instance is not running; alternatively, you can use repozo.py as described at http://www.zope.org/Wikis/ZODB/FileStorageBackup to make a live backup, then create a new Data.fs from that backup in your new instance. Keep your old Data.fs in the old instance as a backup. - Copy the Products and Extensions directories from your old instance into the new instance. Leave the old instance directories intact as a backup. - Update etc/zope.conf with any changes you made in your old instance. (Likewise for zeo.conf if you are using zeo.) - Start the new instance. (Be sure the old instance is not running.) - Update any ZCatalogs as described below. - Update any Python Scripts. This is not strictly necessary, but it will make Zope restart somewhat faster. Visit this URL in your browser: http://.../manage_addProduct/PythonScripts/recompile 2. After moving my old Data.fs to Zope 2.8 I get an "AttributeError, _length" when trying to use the ZCatalog? In Zope 2.8 we cleaned up the index implementations and therefore you need to migrate every single ZCatalog manually. Notice: **YOU SHOULD BACKUP YOUR var/Data.fs file before starting the migration**, see http://www.zope.org/Wikis/ZODB/FileStorageBackup for backup instructions. To perform the migration: - go to the ZMI - click on your ZCatalog instance (or portal_catalog inside your CMF or Plone instance) - you will get an "AttributeError, _length"...don't panic - call the "manage_convertIndexes" method of the ZCatalog (by replacing the "manage_main" part of the URL with "manage_convertIndexes") - depending on the size of your ZCatalog the migration may take a while - after the conversion a message will appear: "Indexes converted and reindexed" 3. CMF doesn't work! Check that you have a recent stable version of CMF. As of Zope 2.8.0, you need at least CMF-1.4.8. CMF is available at http://www.zope.org/Products/CMF/ 4. Plone doesn't work! As of the release of Zope 2.8.0, Plone does not support Zope 2.8 yet. Check http://www.plone.org for updates. General 1. My browser is giving a message, 'Sorry, an error occurred.' How do I find out what the real error is? Step number one in these scenarios is to check the error log on your server. The standard error page should provide you with a link directly to the log entry for that error. If something has gone wrong with the standard error page itself, or if you are using a modified error page, this link may be missing. If this happens, you can visit /event_log/manage_main and browse the recent errors. In general, error_log will show the *traceback* for errors. This traceback explains the error message. Occassionally you won't see any error message. Rather, the HTML source will contain the last good HTML returned by the request before the error occurred. This is due to caching by the browser. Clear your cache and view the HTML source again. 2. I'm using Python 2.x and I'm having a problem ... The correct version of Python should always be automatically detected and used when you configure and install Zope. In general, you should let the configure script do its job and don't try to force an unsupported version of Python! Zope-2.9.4-retire_zpkg/doc/CHANGES.txt0000644000175000017500000002455310447227721017267 0ustar tseavertseaverZope Changes This file contains change information for the current Zope release. Change information for previous versions of Zope can be found in the file HISTORY.txt. To-do - Add cyclic-garbage collection support to C extension classes, especially to acquisition wrappers. N.B: ExtensionClassType already declares that it supports GC (via the Py_TPFLAGS_HAVE_GC flag), but does not appear to conform to the rules for such a type laid out in the Python docs: http://docs.python.org/api/supporting-cycle-detection.html Zope 2.9.4 (unreleased) Bugs fixed - OFS Application: Updated deprecation warnings. Support for '__ac_permissions__' and 'meta_types' will be removed in Zope 2.11, 'methods' support might remain longer. - Collector #2136: Map ResourceLockedError to the correct response code. - Collector #2109: XML-RPC did not handle DateTime.DateTime objects. - Collector #2016: DemoStorage couldn't wrap base storages without an '_oid' attribute. - Collector #2133: standard_error_messages are out of sync. - Updated Five to bugfix release 1.3.6. - Collector #2116: sequence.sort() did not work properly locale related comparison methods - Collector 2077: fixed problem with ACTUAL_URL and SiteRoot - Collector #2073: fixed misbehaviour of OFS.Owned.changeOwnership - Collector #2063: cleaned up some mess in MailHost.sendTemplate() Other Changes - Returned to the "classic" './configure && make && make install' recipe, dropping the use of 'zpkg' for building Zope2 releases. Zope 2.9.3 (2006/05/13) Bugs fixed - Collector #2083: 'make clean' leaves turds. - Collector #2082: 'make install' broken. - Collector #2081: 'make instance' forced inappropriate dir, credentials. - Collector #1447: When editing content on a virtual-hosted zope, AcceleratedHTTPCacheManager now purges the correct URL. - Collector #2062: Fix manage_historyCopy, which was broken, and write tests for it. - Collector #2061: Fix problems where windows line endings are passed to restricted code compilers. - Collector #2072: Applied patch to fix problem with overly restrictive __bobo_traverse__ security and tests. - Added missing Zope 3 packages: zope.app.intid, zope.app.keyreference, zope.app.session, zope.contentprovider, zope.viewlet - Updated Five to bugfix release 1.3.5. - OFS.PropertyManager: Provided missing security declarations. - Products.SiteErrorLog: SiteErrorLog only copied the unformatted traceback to the event.log, missing out on __traceback_supplement__. Zope 2.9.2 (2006/03/27) Bugs fixed - Collector #2051: Applied patch by Yoshinori Okuji to fix some XML export/import problems, and added tests for that feature. - Missing import of NotFound in webdav.Resource. - Collector #2037: fixed broken ACTUAL_URL for '/' - Put the default skin interface on the request once it is created, both in ZPublisher and ZopeTestCase. - Updated Five to bugfix release 1.3.3. See Products/Five/CHANGES.txt for more info. Zope 2.9.1 (2006/02/25) Bugs fixed - Collector #1819: fixed signature of MountedObject.SimpleTrailblazer._construct() - Collector #2019: removed validateValue() from cAccessControl (already removed in former Zope versions from the AccessControl Python implementation) - Collector #1991: ZPublisher did not deal properly with a trailing %20 in the URL - Collector #1989: 'test.py' now copyied to $ZOPE_HOME/bin during installation, which re-enables tests run from the instance home. - zope.app.introspector was not included with the source archive - Collector #2013: improved XHTML conformance of error messages, some of which did not close '

' tags. - Collector #1999: fixed broken FTP rename functionality (RNFR now returns 350 as status code instead 250) - officially deprecated the zLOG module (to be removed in Zope 2.11). Use the logging module of Python instead. - Replaced used of deprecated 'OFS.content_types' module with cognates from 'zope.app.content_types'. - Collector #2002: fixed broken 'ls -R' functionality (didn't recurse properly subclasses of OFS.Folder) Zope 2.9.0 (2006/01/09) Bugs fixed - deprecated OFS.content_types - Fixed ConflictError when using sessions. Zope 2.9.0 beta 2 (2005/12/24) Bugs fixed - Collector #1939: When running as a service, Zope could potentially collect too much log output filling the NT Event Log. When that happened, a 'print' during exception handling would cause an IOError in the restart code causing the service not to restart automatically. Problem is that a service/pythonw.exe process *always* has an invalid sys.stdout. But due to the magic of buffering, small "print" statements would not fail - but once the file actually got written to, the error happened. Never a problem when debugging, as the process has a console, and hence a valid stdout. - For content-type HTTP headers starting with 'text/' or 'application/' the 'charset' field is automatically if not specified by the application. The 'charset' is determined by the content-type header specified by the application (if available) or from the zpublisher_default_encoding value as configured in etc/zope.conf - Collector #1976: FTP STOR command would load the file being uploaded in memory. Changed to use a TemporaryFile. - OFS ObjectManager: Fixed list_imports() to tolerate missing import directories. - Collector #1965: 'get_transaction' missing from builtins without sufficient deprecation notice (ZODB 3.6 properly removed it, but Zope needs to keep it for another release). - Several zope.app packages were forgotten to be included in the first beta due to the now zpkg-based build and release process. Features added - The SiteErrorLog now copies exceptions to the event log by default. - Added a 'conflict-error-log-level' directive to zope.conf, to set the level at which conflict errors (which are normally retried automatically) are logged. The default is 'info'. Zope 2.9.0 beta 1 (2005/12/06) Features added - ObjectManager now has an hasObject method to test presence. This brings it in line with BTreeFolder. - Using FastCGI is officially deprecated - Improved logging of ConflictErrors. All conflict errors are logged at INFO, with counts of how many occurred and how many were resolved. Tracebacks for all conflicts are logged a DEBUG level, although these won't help anyone much. If a conflict error is unresolved, it will now bubble up to error_log and standard_error_message. - Fixed unclear security declarations. Warn when an attempt is made to have a security declaration on a nonexistent method. - updated to ZPL 2.1 - interfaces: Added 'Interfaces' tab to basic core objects. This is a Five feature and only available if the classes are made five:traversable. It allows to inspect interfaces and to assign marker interfaces through the ZMI. - webdav: Added support for the z3 WriteLock interface. It is no longer necessary to have the WriteLockInterface in the __implements__ list of lockable objects. All classes inheriting from LockableItem inherit also the IWriteLock interface. Note that this enables webdav locking for all subclasses by default even if they don't specify the WriteLockInterface explicitly. - App ProductContext: Made registerClass aware of z3 interfaces. Z2 and z3 interfaces are registered side by side in the same tuple in Products.meta_types. IFAwareObjectManagers like the ZCatalog work now with z3 interfaces as well. - Zope now sends Zope 3 events when objects are added or removed from standard containers. manage_afterAdd, manage_beforeDelete and manage_afterClone are now deprecated. See lib/python/Products/Five/tests/event.txt for details. - Zope now utilizes ZODB 3.6. It had previously used ZODB 3.4. As a result, the DBTab package was removed, as ZODB 3.6 has multidatabase support that makes DBTab unnecessary. - Added a 'product-config' section type to zope.conf, allowing arbitrary key-value mappings. Products can look for such confgiurations to set product-specific options. Products mwy also register their own section types, extending the 'zope.product.base' type. (see the example '' section in skel/etc/zope.conf.in for sample usage). - Collector #1490: Added a new zope.conf option to control the character set used to encode unicode data that reaches ZPublisher without any specified encoding. - AccessControl, Acquisition, App, OFS, webdav, PluginIndexes, ZCatalog and ZCTextIndex: Added some Zope 3 style interfaces. This makes the bridged interfaces shipped with Five obsolete. - ZConfig extension, address now also accepts symbolic port names from etc/services (unix) or etc\services (win32) - ZPublisher.HTTPRequest.FileUpload now supports full file object interface. This means Iterator support was added. (for line in fileobject: ..., as well as fileobject.next() and fileobject.xreadlines() ) Collector #1837 - Switched the bundled Zope 3 to release 3.2 and upgraded the Five product to version 1.3 (see Products/Five/CHANGES.txt). - The PageTemplate implementation now uses Zope 3 message catalogs by default for translation. Old-style translation services such as Localizer or PlacelessTranslationService are still supported as fall-backs. See Products/Five/doc/i18n.txt for more information. - Switched to the new improved test runner from Zope 3. Run test.py with -h to find out more. - Collector #1904: On Mac OS X avoid a spurious OSError when zopectl exits. Zope-2.9.4-retire_zpkg/doc/UNITTEST.txt0000644000175000017500000004073610222031003017450 0ustar tseavertseaverZope Unit Testing Zope Testing If you encounter a directory named "tests" in a package within within the Zope source code, it most likely indicates that the directory contains test code used to ensure that the code owned by the package works as it was designed. Many of the test scripts contained within Zope "tests" directories will be scripts which contain "unit tests". What Unit Tests Are A "unit" may be defined as a piece of code with a single intended purpose. A "unit test" is defined as a piece of code which exists to codify the intended behavior of a unit and to compare its intended behavior against its actual behavior. Unit tests are a way for developers and quality assurance engineers to quickly ascertain whether independent units of code are working as expected. Unit tests are generally written at the same time as the code they are intended to test. A unit testing framework allows a collection of unit tests to be run without human intervention, producing a minimum of output if all the tests in the collection are successful. What Unit Tests Are Not It's very useful to define unit tests in terms of what they are not. From the "Extreme Programming Enthusiast" website (http://c2.com/cgi/wiki?UnitTestsDefined):: Unit tests are not: - Manually operated. - Automated screen-driver tests that simulate user input (these are "functional tests"). - Interactive. They run "no questions asked." - Coupled. They run without dependencies except those native to the thing being tested. - Complicated. Unit test code is typically straightforward procedural code that simulates an event. Unit Testing Frameworks A unit testing framework is generally employed to collect related unit tests together in order to make it easier to run them as a group. When used with a unit testing framework, unit tests live outside of the modules of code they're intended to test. How Unit Tests Help In The Development Process Unit tests should be written at the same time the code they test is written. A short, healthy cycle of "code/write test/run test/repeat" can help a developer code more quickly by reducing "backtracking" effort and by helping the developer focus on the actual problem at hand. Additonally, the unit tests generated at initial development time can serve as later assurance that maintenance and refactoring performed on code does not break any of its intended functionality or behavior. The results of unit tests may additionally be used as a metric by quality assurance personnel along with the results of other tests to gauge code quality before before it is "shipped." Basic Unit Testing Philosophies Write unit tests at the same time that you write the code. Nothing's worse than being faced with the prospect of writing tests against a huge chunk of existing code because you "have to." Writing unit tests post-facto can be boring and also robs you of the main benefits that unit testing can provide. Writing unit tests at the same time you write the code helps you focus on the task at hand. Writing unit tests in conjuction with code can be fun and satisfying, and can help you improve the quality of your code while its goals are fresh in your mind. Used properly, unit testing may also help you write code faster, because you will need to "backtrack" less. Some "Extreme Programming" enthusiasts posit that you should write a test before you write its associated code, and then develop the code until it passes the test. Unit tests should be developed against as small and specific a subset of a system's or subsystem's functionality as possible. For instance, a one unit test may test that a unique id generator produces ids of a specific length, while another unit test in the same group may ensure that a thousand ids from the same unique id generator do not contain the same value. Writing a single unit test which tests a broad swath of a system's capabilities is counterproductive, because it does not allow for a fine enough granularity when attempting to figure out "what went wrong," requiring the developer to "backtrack". Unit testing is capable of helping to help reduce backtracking, but only if used properly. A unit test does not produce any output unless it fails. If a unit test fails, it should print something useful, but short. A unit test should never fill the screen with output or otherwise produce output that needs to be manually examined for "clues". This is the realm of other testing methodologies. If unit tests are written at sufficiently granular level, it is often enough just to know the name of the unit test that failed. "It is better to have tried to test and failed than to not have tried to test at all" aka "test the riskist things first." If the prospect of writing a series of unit tests for an existing system seems daunting, it's important to remember that no matter how many unit tests you write, you cannot prove that your software does not have bugs. Therefore, you cannot possibly test every case while developing. You should plan to write tests against code based on the risks involved in not testing that code. Don't feel that you need to write a test case for every "corner case" (although do try to hit the riskiest ones). In the worst case, it's better to have a test module with one lonely unit test in it than none at all. "Test fixtures" are employed by unit tests. Test fixtures are bits of state and environment that allow the unit test to perform its job properly. An example of a test fixture might be a file, an instance of a class, or a row in a database table. Any part of the environment needed by a unit test besides the unit testing framework itself is considered a test fixture. In general, the common fixtures required by individual tests in a testing group should be more or less identical. If the fixtures needed by a single test are radically different than the fixtures required by the rest of the tests, or if the test does not require the fixtures provided to the other tests, it probably belongs in another (or its own) group of tests. When a unit test in a group modifies the state of a test fixture, the test fixture should be restored to a known state before the next unit test in the group is run. Often, this means "rolling back" changes to a transactional database or restoring the state of a string so the next unit test can inherit a known state of the same fixtures. The unit testing framework has capabilities which allow you to automate most of this work by providing a "set up" method which gets called before each test is run and a "tear down" method that gets called after a test is finished. Unit tests should play nicely with the unit testing framework they employ. Unit tests should not call "sys.exit()" or do similar things which effect their ability to be run as part of a group of tests. The testing framework attempts to deal with misbehaved unit tests, but it's better just to make them behave nicely in the first place. Unit tests should "grow" with the code that they're intended to test. For example, if a group of unit tests is intended to verify the behavior of all of the routines within a module, additional unit tests should be added to the test group when new functionality is added to that module. Writing Unit Tests For The Zope Core If you're writing core code, you probably don't need to listen to any more of this. :-) The rules for writing tests for Zope core code are simple: - The testing code should make use of PyUnit (/lib/python/unittest.py). Instructions for using PyUnit are available at http://pyunit.sourceforge.net. - Tests must be placed in a "tests" subdirectory of the package or directory in which the core code you're testing lives. - Test modules should be named something which represents the functionality they test, and should begin with the prefix "test." E.g., a test module for BTree should be named testBTree.py. - An individual test module should take no longer than 60 seconds to complete. Writing Unit Tests For Applications Based On Zope Zope uses the PyUnit unit testing framework, the documentation for which is available at http://pyunit.sourceforge.net. The lib/python/unittest.py module is the framework. You may establish your own conventions for naming and placement of test modules, but using the same rules as for Zope Core is recommended, and the standard used by most. Writing unit tests against applications based on Zope can be difficult. Zope is a collection of related modules, some with non-trivial interdependencies. Running its code successfully also in some cases depends on state provided only in the context of a web request, so calling Zope methods directly may not work as you expect. If you're not intimately familiar with Zope, implementing unit tests can be fustrating. For example, for the common case, before you are able to write code which tests a Zope SQL Method, you must establish a test fixture which represents your entire Zope site. This is made easier by the ZopeTestCase package, included with Zope from Zope 2.8. It is located in the directory lib/python/Testing/ZopeTestCase and the documentation in the doc subdirectory. In principle, subclassing from Testing.ZopeTestCase.ZopeTestCase instead of subclassing from unittest.TestCase will mean that you have a zope test fixture set up for you. There are several examples of how to use ZopeTestCase in the ZopeTestCase directory. If you don't want to do that, you can still set up the fixture yourself. - add the 'lib/python' directory of your Zope installation to the PYTHONPATH (via sys.path.insert()) - 'import ZODB' (may not be required, but just put it in for good measure) - 'import Zope' - 'app = Zope.app()' - operate on the Zope instance space by calling methods from the root object (bound to 'app'), e.g.: app.acl_users.manage_addUser() - a transaction will not be committed to the Zope object database until you call "transaction.commit()", so changes made to the ZODB are not visible to succeeding tests unless that function is called explicitly. - As a part of your tearDown, make sure to call "app._p_jar.close()". This closes the database connection cleanly. For more information on operating on Zope programatically by "importing" it, see Michel Pelletier's "The Debugger Is Your Friend" at http://www.zope.org/Members/michel/HowTos/TheDebuggerIsYourFriend Running the unit tests The basic command to run unit tests is:: bin/python bin/test.py --config-file etc/zope.conf or on windows:: C:\Path\To\Python.exe bin\test.py --config-file etc\zope.conf This will run all unit tests in lib/python and below (that is, it will run the zope core unit tests. To run the unit tests located in the Products directory you need to add two parameters --libdir Products so that test.py will look for modules in the Products directory, and --dir Products to look for tests in the Products directory and below. You can of course specify --dir even closer, so a typical command to run the tests for the "Myproduct" product would be bin/python bin/test.py -v --config-file etc/zope.conf --libdir Products \ --dir Products/Myproduct This is rather long, and on unix you can shorten this to:: bin/zopectl test --dir Products/Myproduct These commands are equivalent. bin/zopectl will just run test.py with some useful defaults for you:: -v increases verbosity. You can add -vv for even more output. --config-file etc/zope.conf reads in the Zope configuration file,so that important paths are set up. --libdir Products tells test.py to include Products as a module path and to include the tests there. To see the rest of the command options you can run it with --help:: bin/zopectl test --help The test output should look something like this:: Running unit tests at level 1 Running unit tests from /home/zope/Products/CMFCore/tests Parsing /home/zope/etc/zope.conf ..................... ---------------------------------------------------------------------- Ran 21 tests in 0.130s OK Speeding up the tests Not all unit tests will need a zope test fixture. If you have many tests that do not need it, it can be a good idea to separate them into different test files, so that you can run the tests that do not need a fixture separately, since setting up the fixture takes time. This will not save you time when running all your tests, but it can save time while developing, since you can skip loading Zope when running some tests (also see Functional testing, below). Also, one of the most effective tools for facilitating unit testing is ZEO (http://www.zope.org/Products/ZEO). ZEO is an open-source clustering solution for Zope which makes it possible to front-end a single "storage server" which manages a Zope object database with multiple Zope clients that run a "client storage". The reason ZEO is interesting for unit testing is mostly an unintended side-effect of how it works as compared to Zope without ZEO. Zope without ZEO commonly uses a "FileStorage" to hold its object database. When Zope is started with a FileStorage, the FileStorage code processes an "index" file. This takes time. Zope using a ClientStorage as with ZEO does not process an index file, making startup faster. Fast startup of Zope is critical to effective unit testing. It is recommended that you implement ZEO if you're heavy in to unit testing, as it really speeds things up. It's not strictly required, however. Emulating requests Sometimes, just importing Zope isn't enough. For example, it's often not possible to obtain the results of a DTML or Python method by simply calling it from your running code without doing lots of trickery by establishing fake REQUEST object to pass in to it, as Zope expects a REQUEST object to exist in the context of a web request (which a DTML method is somewhat logically designed to serve). There are two ways of doing this. The old and complicated way is using Zope.debug() (documented below), but the new way is known as "functional tests". Support for this is included in ZopeTestCase, see lib/python/Testing/ZopeTestCase/doc/FunctionalTesting.stx for more information. It does almost the same thing as the "debug" method, but it returns a RESPONSE object, so you can easily check that the output is correct, and not only that the request finished without raising any exceptions. Zope.debug() Zope.debug() allows you to simulate a web request, which generally provides all the state necessary to run methods which depend on web requests, and returns the results of the web request as it would be seen in by a web browser. To use the Zope debug method, do the following: - add the lib/python path to your PYTHONPATH (via sys.path.insert()) - 'import ZODB' - 'import Zope' - 'Zope.debug('/a/url/representing/a/method?with=a?couple=arguments', u='username:password', s='silent', e={'some':'environment', 'variable':'settings'}) The "silent" option causes Zope not to print anything. You can set your python's stdout to a file or a file-like object to capture the output if you do not set the silent flag. Administrivia Unit test scripts found in the Zope source code make use of Pythons PyUnit unit testing framework, written by Stephen Purcell (thanks Stephen!). PyUnit is based on the JUnit testing framework for Java (written by Kent Beck and Erich Gamma), which in turn was based on a testing framework designed for Smalltalk (also written by Kent Beck). Unit testing is a primary tenet of "Extreme Programming", a software development methodology designed to faciliate the rapid production of high quality code with a minimum of developmental ceremony. For more information on unit tests as they relate to Extreme Programming, see http://c2.com/cgi/wiki?UnitTestsDefined. Although Zope Corporation has not embraced the entire spectrum of Extreme Programming methodologies in its software development process, we've found unit tests a way to speed development and produce higher-quality code. ZopeTestCase was written by Stefan H. Holek, and is included with Zope from Zope 2.8. (Thanks Stefan!) Zope-2.9.4-retire_zpkg/doc/HELPSYS.txt0000644000175000017500000001116310050234363017325 0ustar tseavertseaverZope Help System The Zope Help System provides context-sensitive on-line help for Zope users. The system is flexible and can provide help for Python and ZClass-based Zope Products. In the future the Help System will be expanded to provide additional help including API documentation. Using the Help System Every standard Zope management screen should include a help button which provides access to help for that screen. Additionally all the installed help topics can be browsed and searched. Architecture The Help System is based around Zope Products. When a product is installed, its help objects are installed along with it. All help content is associated with a product. Help content is provided by 'Help Topic' objects. These objects live inside Product folders within a special container object called a 'Product Help' object. When you browse a Product folder in the Control Panel you will see these 'Product Help' objects and their 'Help Topics'. In general you get access to the Help System through the help system object which has methods for drawing help buttons. This object lives in the Zope application object and has an id of 'HelpSys'. Writing Help for ZClasses Suppose you've created an addable type of object with ZClasses. You'd like the management screens of your objects to have help buttons just like the standard Zope management screens. First create some Help Topics though the web which document your management screens. Do this by going to your ZClass's Product and creating new Help Topics inside the Product Help object. Next go to your ZClass and click on the 'Views' management tab. On this screen you define your object's management views. Each view has a name, a method, and optionally a help topic. If you select a help topic for a view, a help button will be drawn on that management view and it will be linked to the help topic you select. Writing Help for Python Products To support help your Python product needs to register help topics during product registration, and it needs to indicate which help topics should be associated with which management screens. Registering Help Topics To register help topics use the 'registerHelp' method on the ProductContext object. For example:: def initialize(context): ... context.registerHelp() This method will create help topics for all files found in the 'help' subdirectory of the product. Supported file types include: .html, .htm, .txt, .stx, .dtml, .gif, .jpg, .png. Appropriate classes of help topics are used depending on the suffix of the help files. If you want more control over how your help topics are created you can use the 'registerHelpTopic' method that takes an id and a help topic object as arguments. For example:: from mySpecialHelpTopics import MyTopic def initialize(context): ... context.registerHelpTopic('myTopic', MyTopic()) Associating Help Topics with Management Screens The chief way to bind a help topic to a management screen is to include information about the help topic in the class's 'manage_options' structure. For example:: manage_options=( {'label':'Edit', 'action':'editMethod', 'help':('productId','topicId')}, ) In this example, 'productId' refers to the name of the Zope Product in which the class is defined, and 'topicId' refers to the id of the Help Topic associated with this management view. When Zope draws the management view it will automatically include a help button pointing to the right help topic if you provide this information in the 'manage_options' structure. Note: sometimes Zope gets confused and defaults to highlighting the first management tab in place of the correct one. To fix this, set the 'management_view' variable to the name of the correct view. If the wrong view is hilighted, then the wrong help button will be drawn. To draw a help button on a management screen that is not a view, use the 'HelpButton' method of the 'HelpSys' object like so:: This will draw a help button linked to the specified help topic. If you prefer to draw your own help button you can use the helpURL method instead like so:: This will give you a URL to the help topic. You can choose to draw whatever sort of button or link you wish. Zope-2.9.4-retire_zpkg/doc/ZOPE3.txt0000755000175000017500000002035410252354405017047 0ustar tseavertseaverUsing Zope 3 Components in Zope 2 Applications Background Zope 3 is the next major revision of Zope. It is designed to be more 'programmer-centric' and easier to learn, use and extend. Zope 3 introduces an interface-centric component architecture that makes it easier to develop and deploy components without requiring developers to learn and understand the entire Zope framework. Much more information on Zope 3 is available on the Zope 3 area of the zope.org Website at http://dev.zope.org/Zope3/. As of Zope 2.8, the "Five" project has been integrated into the Zope 2 core. The "Five" project implements a compatibility layer that allows many Zope 3 components and patterns to be used in new and existing Zope 2 applications. This provides a number of benefits:: - availability of Zope 3 technologies in Zope 2 like the component architecture and declarative configuration - you can gradually evolve your Zope 2 projects to better plan for migration to Zope 3 - you start learning about Zope 3 right now, preparing yourself better for the future. Since Zope 3 is open to contributions, you could even influence your future for the better ;) Features The Five integration layer provides support for Zope 3 interfaces, Zope Configuration Markup Language (ZCML), adapters, views, utilities, schema-driven content, and Zope 3 add and edit forms. Note that the Five layer does *not* attempt to provide a ZMI user interface for Zope 3 components. Zope 2.8+ includes the essential Zope 3 packages, so it is not necessary to install Zope 3. Zope 3 Interfaces Everything in the zope.interface package should work. Zope 3 interfaces are the foundation of the component architecture, and also the foundation of schemas. Historically, Zope 2 has used the ``__implements__`` class attribute for interface declarations. Zope 2 cannot detect Zope 3 interfaces and the Zope 3 machinery cannot detect Zope 2 interfaces. This is a good thing, as Zope 2 has no way to deal with Zope 3 interfaces, and Zope 3 cannot work with Zope 2 interfaces. This means you can safely make a class declare both a Zope 2 and Zope 3 interface independently from each other. It's a rare case where you need this - you're usually better off just switching to ``implements()`` for your application if possible. Switching from Zope 2 interfaces to Zope 3 interfaces is easy -- just make your interfaces inherit from ``zope.interface.Interface`` instead of ``Interface.Interface`` (or ``Interface.Base``). Next, change all ``__implements__`` to ``implements()``. You will also have to change any calls to ``isImplementedBy`` and such in your application to ``providedBy``, as ``isImplementedBy`` has been deprecated (you'll see the DeprecationWarnings in your Zope log). ZCML ZCML is the Zope Configuration Markup Language, an XML application. Zope 3 code consists of a lot of components that can be plugged together using ZCML. If you put a 'site.zcml' in the home directory of your Zope instance, this is the root of the ZCML tree. An example of 'site.zcml' is in 'site.zcml.in'. If you don't place a site.zcml, Five falls back on 'fallback.zcml'. ZCML in Zope 2 with Five has a special directive, 'five:loadProducts', to load the ZCML ('meta.zcml', 'configure.zcml') of all installed Zope 2 products, if available. Another special directive, 'five:loadProductsOverrides' is available to load any overriding ZCML (overrides.zcml) in these products. In the 'overrides.zcml' you can override existing views or adapters, in this or in other products. The Five integration layer tries to use the Zope 3 ZCML directives where possible, though it does sometimes support only a subset of the possible attributes. It also introduces a few directives of its own under the ``five`` namespace. The supported directives are listed per namespace in alphabetic order below. zope ``http://namespaces.zope.org/zope`` ======================================== adapter ------- Hook an adapter factory to an interface. content ------- Declare interface and permissions on content object. Declares Zope 2 permissions. permission ---------- Way to make Zope 2 permissions available to Five, ``title`` is permission name. redefinePermission ------------------ Redefine a permission in included ZCML as another one. service ------- Declare a global service serviceType ----------- Declare a type of service. skin ---- Declare a skin, consisting of layers. utility ------- Declare a global utility. browser ``http://namespaces.zope.org/browser`` ============================================== page ---- Declare a page view for an interface. Permission is a Zope 2 permission. pages ----- Declare multiple page views for an interface. Permissions are Zope 2 permissions. defaultView ----------- Declare the name of the view that should be used for the default when viewing the object; i.e. when the object is traversed to without a view. defaultSkin ----------- Declare the default skin used. interface --------- Define an interface in ZCML. layer ----- Declare a layer. menu ---- Declare a menu menuItem, menuItems ------------------- Declare menuItems five ``http://namespaces.zope.org/five`` ======================================== implements ---------- Make a class declare it implements an interface. loadProducts ------------ Loads ZCML in all Zope 2 products. First processes all ``meta.zcml`` files, then processes all ``configure.zcml`` files. loadProductsOverrides --------------------- Loads overriding ZCML in all products (``overrides.zcml``). traversable ----------- Make a Zope 2 content class traversable in the Zope 3 manner using Five. This is used to attached views, resources and other things to Zope 2 objects. defaultViewable --------------- Make a Zope 2 content class use a Zope 3 default view when looking at it without any paths appended to it. This works then instead of ``index_html`` in Zope 2. pagesFromDirectory ------------------ Load all *.pt files in a directory as pages. Useful when you want to share templates between Five and CMF, so you can declare pages like this is a similar way to setting up skin folders in portal_skins. browser:editform ---------------- Create an edit form based on a schema. browser:addform --------------- Create an add form based on a schema. Adapters Generally, adapters can now be used in Zope 2 just as they are used in Zope 3. Zope 3 Views Zope 3 views work in Zope 2 with Five, including layers and skins. To make them work however, you need to make a Zope 2 class "traversable". This can be done by using the 'five:traversable' directive in ZCML. Schemas and Forms With the Five layer, it is possible to use schema-based content using the standard Zope 3 patterns. Security declarations Five aims to eradicate declareProtected, ClassSecurityInfo and initializeClass from your Zope 2 code. In order to do this, Five provides the Zope 3 way of declaring permissions from ZCML, but uses the Zope 2 mechanisms to actually set them. To declare permissions for methods and templates on views you use the permission attribute on the browser:page directive, and specify a Zope 2 permission (given a Zope 3 name). You can find a list of these permissions in permissions.zcml in Five. The permission check takes place before the view is executed. The content directive can also be used to declare permissions on Zope 2 content classes. Note however that these permissions will be ignored by views anyway, as they are trusted -- it only serves to protect directly exposed methods on content classes (the python scripts and the ZPublisher). Zope-2.9.4-retire_zpkg/doc/WINDOWS.txt0000644000175000017500000000477310227347257017356 0ustar tseavertseaverHow to build and install Zope from source code on Windows. ---------------------------------------------------------- These instructions appear to work for 2.7 and the trunk: * Ensure you have the correct MSVC version installed for the version of Python you will be using. * Install (or build from sources) Python http://www.python.org * Install (or build from sources) the Python for Windows extensions http://sourceforge.net/projects/pywin32/ * Unpack the Zope source distribution or pull from CVS. Change to that directory. * Execute: % python.exe inst\configure.py It should say something like: > > - Zope top-level binary directory will be c:\Zope-2.7. > - Makefile written. > > Next, run the Visual C++ batch file "VCVARS32.bat" and then "nmake". (run 'configure.py --help' to see how to change things) * 'makefile' will have ben created. As instructed, execute 'nmake'. If the build succeeds, the last message printed should be: > Zope built. Next, do 'nmake install'. * As instructed, execute 'nmake install'. A few warnings will be generated, but they can be ignored. The last message in the build process should be: > Zope binaries installed successfully. * If you are running from CVS, the build may fail: See http://collector.zope.org/Zope/1530 > running install_data > error: can't copy 'version.txt': no matching files > NMAKE : fatal error U1077: '"e:\src\python-2.3-cvs\pcbuild\python.exe"' : return code '0x1' > Stop. If you see this error, edit setup.py and comment the line referencing 'version.txt' * Zope itself has now been installed. We need to create an instance. Run: % python.exe {install_path}\bin\mkzopeinstance.py We will be prompted, via the console, for the instance directory and username/password for the admin user. * We are now ready to start zope. Run: % {zope_instance}\run_zope.bat. Zope should start with nice log messages being printed to stdout. When Zope is ready, you should see: > ------ > 2004-10-13T12:27:58 INFO(0) Zope Ready to handle requests Press Ctrl+C to stop this instance of the server. * Optionally, install as a Windows service. Execute: % python {zope_instance}\zope_service.py to see the valid options. You may want something like: % python {zope_instance}\zope_service.py --startup=auto install Once installed, it can be started any number of ways: - python {zope_instance}\zope_service.py start - Control Panel - net start service_short_name (eg, "net start Zope_-1227678699" Zope-2.9.4-retire_zpkg/doc/RESTRUCTUREDSTEXT.txt0000644000175000017500000000250710050234363020763 0ustar tseavertseaverIntegration of reStructuredText (reST) in Zope: Zope 2.7 or higher integrates reST as part of the Python docutils package. The syntax of reST is defined under http://docutils.sf.net/spec/rst/introduction.html Usage inside DTML: Usage inside ZPT: Usage inside PythonScripts: from Products.PythonScripts.standard import restructured_text rendered_html = restructured_test(rest_txt) return rendered_html Usage inside Zope products: from reStructuredText import HTML rendered_html = HTML(rest_txt) ... Character set issues: reST processes the reST document internally using unicode. A reST document is converted using Pythons default encoding to unicode and converted back from unicode to the default encoding on the output side. This means you must ensure that Python default encoding is properly. You can customize the default encoding by creating a file sitecustomize.py somewhere in yout PYTHONPATH: import sys sys.setdefaultencoding("iso-8859-1") This version of Zope also includes the ZReST product written by Richard Jones. ZRest is a standalone Zope product to handle reStructuredText documents. Zope-2.9.4-retire_zpkg/doc/DEBUGGING.txt0000644000175000017500000000544510222031003017462 0ustar tseavertseaver Running Zope in Debug Mode If you wish to run Zope in debug mode, set the 'debug-mode' configuration file parameter to 'on' (this is the default). This will have the following effects:: o On UNIX, Zope will not detach from the controlling terminal. o The Z_DEBUG_MODE environment variable gets set, which causes behavioral changes to Zope appropriate for software development. See the configuration file description of 'debug-mode' for more information. Using 'zopectl debug' In Zopes 2.7 and better, a utility known as 'zopectl' is installed into generated instance homes. You can use it to inspect a Zope instance's running state via an interactive Python interpreter by passing zopectl the 'debug' parameter on the command line. The 'top-level' Zope object (the root folder) will be bound to the name 'app' within the interpreter. You can then use normal Python method calls against app and use the Python interpreter normally to inspect results:: [chrism@james Trunk]$ bin/zopectl debug Starting debugger (the name "app" is bound to the top-level Zope object) >>> app.objectIds() ['acl_users', 'Control_Panel', 'temp_folder', 'browser_id_manager', 'session _data_manager', 'error_log', 'index_html', 'standard_error_message', 'standa rd_html_footer', 'standard_html_header', 'standard_template.pt'] >>> Using the Medusa Monitor NOTE: as of Zope 2.7, the Medusa monitor client is known to have operational problems due to lack of maintenance. It may work, it may not. If it doesn't work as advertised, please try 'zopectl debug' instead. If you're running Zope with a medusa monitor port, you can connect and interact via a python prompt with a running Zope session, while others interact with it over the web. Some constraints: o You must connect to a server running on the local host. o You must authenticate as superuser. o At the time of writing the superuser password (in the access file) must be plain text, not encrypted. To use the monitor, start it from the shell prompt like so (as if from the Zope root): python lib/python/ZServer/medusa/monitor_client.py localhost 8099 You'll get back a python prompt. To connect with the running Zope session: >>> import Zope >>> app = Zope.app() >>> dir(app.Control_Panel.Products) ['ExternalMethod', 'MIMETools', 'MailHost', 'OFSP', 'ZCatalog', 'ZGadflyDA', 'ZSQLMethods', '_objects'] >>> To see ODB changes caused by access concurrent with your debug session (eg, those web connections that can still be happening, or other debug sessions!), you may have to do a bit of magic: >>> app._p_jar.sync() To commit changes you make, before exiting, you may have to do another bit of magic: >>> import transaction >>> transaction.commit() Zope-2.9.4-retire_zpkg/doc/SETUID.txt0000644000175000017500000000267710050234363017205 0ustar tseavertseaverZope effective user support Zope can bind its network service to low ports such as 21 (FTP) and 80 (HTTP). In order to bind to low ports, Zope must be started as the root user. However, Zope will only run as root long enough to bind to these low ports. It will then attempt to setuid to a less privileged user. You must specify the user to which Zope will attempt to setuid by changing the 'effective-user' parameter in the zope.conf configuration file to an existing username or UID. All runtime files will be written as this user. If you do not specify an 'effective-user' in the configuration file, and you attempt to start Zope, it will refuse to start. Zope additionally emits a warning if you specify 'nobody' as the 'effective-user'. The rationale for this warning stems from the fact that, historically, many other UNIX services dropped privileges to the 'nobody' account after starting as root. Any security defects in these services could cause someone to gain access as the 'nobody' account on your system. If someone was to gain control of your 'nobody' account they could compromise your Zope files. The most important thing to remember about effective user support is that you don't have to start Zope as root unless you want to listen for requests on low ports (ports beneath 1024). In fact, if you don't have this need, you are much better off just starting Zope under a dedicated user account. Zope-2.9.4-retire_zpkg/doc/CREDITS.txt0000644000175000017500000000422610050234363017275 0ustar tseavertseaverCredits The Zope software receives contributions from far and wide. Here's the Zope Hall of Fame: o Stephen Purcell allows us to distribute his PyUnit unit testing framework with Zope. o Jeff Bauer is Zope Dude Number One. Jeff took over PCGI and kept pushing it forward through the years. o Sam Rushing worked with us at Digital Creations to make Medusa the publishing platform for ZServer and the concurrency of Zope2. o A subset of windows guru Mark Hammond's win32 extensions are bundled with win32 binary distributions of Zope. o Martijn Pieters and Brian Hooper contributed the #in reverse attribute. o Phillip Eby contributed the DTML 'let' tag and many other useful ideas, including the inspiration for the DTML 'call', 'with' and 'return' tags. o The DateTime module was based on work from Ted Horst. o Jordan Baker contributed the 'try' tag, something we've wanted for a long, long time. o Martijn Pieters chipped in with a safe range function. o Michael Hauser came up with the name "Zope". o Eric Kidd from Userland contributed to ZPublisher's support for XML-RPC. o Andrew M. Kuchling wrote the initial version of mod_pcgi, making him extremely cool in our book. o Oleg Broytmann has taken up the standard of mod_pcgi and moving it to be a really amazing thing, and ready for prime time. o Jephte CLAIN made some patches to European ZopeTime. o Thanks to Gregor Hoffleit for his work in getting Zope into the Debian distribution. o All the other Zopistas far and wide that stuck with us during the Bobo/Principia days and politely push us to make the best damn app server on this or any other planet. o Of course the list of credits would be quite incomplete without mentioning Guido van Rossum, benevolent dictator of Python and long-time friend of Digital Creations. Zope Power is Python Power. o Special thanks to Richard Stallman and the Free Software Foundation for their assistance and feedback on the GPL-compatible 2.0 version of the Zope Public License. Zope-2.9.4-retire_zpkg/doc/ZODB.txt0000644000175000017500000000627410223052726016746 0ustar tseavertseaverThe Zope Object Database, ZODB, version 3.0 ZODB is the next generation of our object database architecture. It provides a number of advantages over or existing databases: - Support for concurrency, - Well-defined storage management interface that will allow many different storage management strategies to be used, from file storage, to RDBMS storage, to memory storage, - More robust file storage format, - Much better version support and integrations of versions with the transaction system. For example, it is possible to commit from one version to another, to undo version commit and abort, and to use "temporary versions" to reduce memory use when manipulating large quantities of data. - Support for multiple databases in the same object system. - Support for multi-process storage managers, although the standard distribution will not include any multiple process storage managers. Note: Using ZODB 3 from Python In ZODB 2, you could access the top-level application object with:: import Main app=Main.app You could then navigate from the top-level object by getting attributes, calling methods, etc.. In ZODB 3, you get the top-level object like this:: import Zope app=Zope.app() ... do stuff with objects # and when you're done: app._p_jar.close() You have to import the Zope application module, which uses ZODB 3 rather than ZODB 2. In ZODB 3, you have to get a connection to a database before you access an object. The 'app()' function combines opening a connection and getting the top level object. When your done using the top-level object (or any objects accessible from it) you can close the database connection by calling the 'close' method on the '_p_jar' attribute, which is the database connection. You don't need to close the connection if you are going to exit Python without doing any more work. Don't forget to:: import transaction transaction.commit() If you want any changes to made to be saved. Note: Converting ZODB 2 (aka BoboPOS) data files to ZODB 3. The bbb.py script in utilities can be used to convert data files from ZODB 2 to ZODB 3 format:: utilities/bbb.py -f output_file input_file Here's a example:: utilities/bbb.py -f var/Data.fs var/Data.bbb You can also convert export files from ZODB 2 by inclding the -x option:: utilities/bbb.py -x -f output.zexp input.bbe ZODB 3 and Zope Database Adapters Most database adapters are *currently* likely to be problematic unless the underlying extensions and libraries: - allow multiple simultaneous database connections, - are thread safe, - give up the Python global interpreter lock when making database calls. This is only a problem when running Zope 2 with multiple threads. ZODB 3 Futures These are features that are lkely to wait for releases after 2.0. - Multiple database support - OPTIMIZATION: FileStorage will get a more efficient data structure for maintaining index information and key methods in the ZODB framework will move to C. Zope-2.9.4-retire_zpkg/doc/SIGNALS.txt0000644000175000017500000000157210050234363017301 0ustar tseavertseaverSignals (POSIX only) Signals are a POSIX inter-process communications mechanism. If you are using Windows then this documentation does not apply. Zope responds to signals which are sent to the process id specified in the file '$INSTANCE_HOME/var/Z2.pid':: SIGHUP - close open database connections, then restart the server process. A idiom for restarting a Zope server is: kill -HUP `cat $INSTANCE_HOME/var/z2.pid` SIGTERM - close open database connections then shut down. A common idiom for shutting down Zope is: kill -TERM `cat $INSTANCE_HOME/var/Z2.pid` SIGINT - same as SIGTERM SIGUSR2 - close and re-open all Zope log files (z2.log, event log, detailed log.) A common idiom after rotating Zope log files is: kill -USR2 `cat $INSTANCE_HOME/var/z2.pid` Zope-2.9.4-retire_zpkg/lib/0000755000175000017500000000000010447233620015441 5ustar tseavertseaverZope-2.9.4-retire_zpkg/lib/python/0000755000175000017500000000000010447233702016763 5ustar tseavertseaverZope-2.9.4-retire_zpkg/lib/python/TAL/0000755000175000017500000000000010447233607017407 5ustar tseavertseaverZope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/0000755000175000017500000000000010447233607021341 5ustar tseavertseaverZope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml10.html0000644000175000017500000000767110050234363023331 0ustar tseavertseaver A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal01.html0000644000175000017500000000001110050234363023126 0ustar tseavertseaverbaseline Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal10.html0000644000175000017500000000771010050234363023143 0ustar tseavertseaver A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal02.html0000644000175000017500000000764010050234363023146 0ustar tseavertseaver A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal11.html0000644000175000017500000000776510050234363023156 0ustar tseavertseaver A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal03.html0000644000175000017500000000055010050234363023140 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal12.html0000644000175000017500000000073710050234363023147 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal04.html0000644000175000017500000000033310050234363023140 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal05.html0000644000175000017500000000061710050234363023146 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal06.html0000644000175000017500000000073510050234363023150 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal07.html0000644000175000017500000000551110050234363023146 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal08.html0000644000175000017500000000731110050234363023147 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/tal09.html0000644000175000017500000000062010050234363023144 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml01.html0000644000175000017500000000001110050234363023306 0ustar tseavertseaverbaseline Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml11.html0000644000175000017500000000773610050234363023334 0ustar tseavertseaver &dtml-x0; A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml02.html0000644000175000017500000000764010050234363023326 0ustar tseavertseaver A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. A large chunk of text to be repeated. Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml12.html0000644000175000017500000000061310050234363023320 0ustar tseavertseaver &dtml-y0; &dtml-y1; &dtml-y2; &dtml-y3; &dtml-y4; &dtml-y5; &dtml-y6; &dtml-y7; Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml03.html0000644000175000017500000000045010050234363023317 0ustar tseavertseaver &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml04.html0000644000175000017500000000025410050234363023322 0ustar tseavertseaver &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml05.html0000644000175000017500000000050010050234363023315 0ustar tseavertseaver &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml06.html0000644000175000017500000000056010050234363023324 0ustar tseavertseaver &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml07.html0000644000175000017500000000451110050234363023325 0ustar tseavertseaver &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml08.html0000644000175000017500000000451110050234363023326 0ustar tseavertseaver &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; Zope-2.9.4-retire_zpkg/lib/python/TAL/benchmark/dtml09.html0000644000175000017500000000050110050234363023322 0ustar tseavertseaver &dtml-x0; &dtml-x1; &dtml-x2; &dtml-x3; &dtml-x4; &dtml-x5; &dtml-x6; &dtml-x7; Zope-2.9.4-retire_zpkg/lib/python/TAL/markupbase.py0000644000175000017500000002500410050234363022102 0ustar tseavertseaver"""Shared support for scanning document type declarations in HTML and XHTML.""" import re, string _declname_match = re.compile(r'[a-zA-Z][-_.a-zA-Z0-9]*\s*').match _declstringlit_match = re.compile(r'(\'[^\']*\'|"[^"]*")\s*').match del re class ParserBase: """Parser base class which provides some common support methods used by the SGML/HTML and XHTML parsers.""" def reset(self): self.lineno = 1 self.offset = 0 def getpos(self): """Return current line number and offset.""" return self.lineno, self.offset def error(self, message): """Return an error, showing current line number and offset. Concrete subclasses *must* override this method. """ raise NotImplementedError # Internal -- update line number and offset. This should be # called for each piece of data exactly once, in order -- in other # words the concatenation of all the input strings to this # function should be exactly the entire input. def updatepos(self, i, j): if i >= j: return j rawdata = self.rawdata nlines = rawdata.count("\n", i, j) if nlines: self.lineno = self.lineno + nlines pos = rawdata.rindex("\n", i, j) # Should not fail self.offset = j-(pos+1) else: self.offset = self.offset + j-i return j _decl_otherchars = '' # Internal -- parse declaration (for use by subclasses). def parse_declaration(self, i): # This is some sort of declaration; in "HTML as # deployed," this should only be the document type # declaration (""). rawdata = self.rawdata import sys j = i + 2 assert rawdata[i:j] == "' n = len(rawdata) decltype, j = self._scan_name(j, i) if j < 0: return j if decltype == "doctype": self._decl_otherchars = '' while j < n: c = rawdata[j] if c == ">": # end of declaration syntax data = rawdata[i+2:j] if decltype == "doctype": self.handle_decl(data) else: self.unknown_decl(data) return j + 1 if c in "\"'": m = _declstringlit_match(rawdata, j) if not m: return -1 # incomplete j = m.end() elif c in "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ": name, j = self._scan_name(j, i) elif c in self._decl_otherchars: j = j + 1 elif c == "[": if decltype == "doctype": j = self._parse_doctype_subset(j + 1, i) else: self.error("unexpected '[' char in declaration") else: self.error( "unexpected %s char in declaration" % `rawdata[j]`) if j < 0: return j return -1 # incomplete # Internal -- scan past the internal subset in a n: # end of buffer; incomplete return -1 if rawdata[j:j+4] == "

Some headline

This is the real contents of the bottom right slot.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.



Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test11.xml0000644000175000017500000000072110050234363023541 0ustar tseavertseaver

dummy text

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test14.xml0000644000175000017500000000044610050234363023550 0ustar tseavertseaver

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test02.html0000644000175000017500000000714410050234363023713 0ustar tseavertseaver sample1 a simple invoice
01786 2000-03-17 55377 2000-03-15 GJ03405 DAVE 1 2000-03-17 K5211(34) 23 23
SHIPWRIGHT RESTAURANTS LIMITED 125 NORTH SERVICE ROAD W WESTLAKE ACCESS NORTH BAY L8B1O5 ONTARIO CANADA ATTN: PAULINE DEGRASSI 1 CS DM 5309 #1013 12 OZ.MUNICH STEIN 37.72 37.72 6 DZ ON 6420 PROVINCIAL DINNER FORK 17.98 107.88 72 EA JR20643 PLASTIC HANDLED STEAK KNIFE .81 58.32 6 DZ ON 6410 PROVINCIAL TEASPOONS 12.16 72.96 0 DZ ON 6411 PROVINCIAL RD BOWL SPOON 6 17.98 0.00 1 EA DO 3218 34 OZ DUAL DIAL SCALE AM3218 70.00 5.0 66.50 1 CS DM 195 20 OZ.BEER PUB GLASS 55.90 55.90 399.28 3.50 23.75 29.61 33.84 33.84 486.48 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test20.html0000644000175000017500000000005510050234363023705 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test16.xml0000644000175000017500000000025310050234363023546 0ustar tseavertseaver bar Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test12.html0000644000175000017500000000154110050234363023707 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test04.html0000644000175000017500000000130310050234363023704 0ustar tseavertseaver
  • 1

use-macro fill-slot

use-macro

define-slot

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test17.xml0000644000175000017500000000050010050234363023542 0ustar tseavertseaver No No Yes No Yes Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test14.html0000644000175000017500000000031710050234363023711 0ustar tseavertseaver

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test18.xml0000644000175000017500000000124010050234363023545 0ustar tseavertseaver

Content

Content

Content

No

No

Yes

Yes

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test36.html0000644000175000017500000000037210075023435023721 0ustar tseavertseaver some text Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test_metal3.html0000644000175000017500000000011410050234363025004 0ustar tseavertseaverShould not get attr in metal Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test06.html0000644000175000017500000000023410050234363023710 0ustar tseavertseaver dummy body in test6 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test34.html0000644000175000017500000000036710050234363023720 0ustar tseavertseaver stuff more stuff stuff more stuff Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test_metal5.html0000755000175000017500000000026110050234363025014 0ustar tseavertseaver Z3 UI Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test16.html0000644000175000017500000000024010050234363023706 0ustar tseavertseaverblah, blah Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test08.html0000644000175000017500000000473310050234363023722 0ustar tseavertseaver

Some headline

This is the real contents of the bottom right slot.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test18.html0000644000175000017500000000101710050234363023713 0ustar tseavertseaver

Content

Content

Content

No

No

Yes

Yes

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test_metal7.html0000755000175000017500000000017710050234363025024 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test01.xml0000644000175000017500000000270710050234363023546 0ustar tseavertseaver dadada

This title is not displayed

Title

 &HarryPotter;

foo bar

  • Car Name
    •
python python Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test02.xml0000644000175000017500000000717310050234363023551 0ustar tseavertseaver sample1 a simple invoice
01786 2000-03-17 55377 2000-03-15 GJ03405 DAVE 1 2000-03-17 K5211(34) 23 23
SHIPWRIGHT RESTAURANTS LIMITED 125 NORTH SERVICE ROAD W WESTLAKE ACCESS NORTH BAY L8B1O5 ONTARIO CANADA ATTN: PAULINE DEGRASSI 1 CS DM 5309 #1013 12 OZ.MUNICH STEIN 37.72 37.72 6 DZ ON 6420 PROVINCIAL DINNER FORK 17.98 107.88 72 EA JR20643 PLASTIC HANDLED STEAK KNIFE .81 58.32 6 DZ ON 6410 PROVINCIAL TEASPOONS 12.16 72.96 0 DZ ON 6411 PROVINCIAL RD BOWL SPOON 6 17.98 0.00 1 EA DO 3218 34 OZ DUAL DIAL SCALE AM3218 70.00 5.0 66.50 1 CS DM 195 20 OZ.BEER PUB GLASS 55.90 55.90 399.28 3.50 23.75 29.61 33.84 33.84 486.48 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test03.xml0000644000175000017500000000064710050234363023551 0ustar tseavertseaver

outer variable x, first appearance inner variable x outer variable x, second appearance

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test04.xml0000644000175000017500000000133210050234363023542 0ustar tseavertseaver
  • 1

use-macro fill-slot

use-macro

define-slot

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test01.html0000644000175000017500000000266010050234363023710 0ustar tseavertseaver dadada

This title is not displayed

Title

 &HarryPotter;

foo bar

  • Car Name
    •
python python Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test05.xml0000644000175000017500000000025110050234363023542 0ustar tseavertseaver

This is the body of test5

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test11.html0000644000175000017500000000072110050234363023705 0ustar tseavertseaver

dummy text

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test06.xml0000644000175000017500000000026210050234363023545 0ustar tseavertseaver dummy body in test6 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test03.html0000644000175000017500000000062010050234363023704 0ustar tseavertseaver

outer variable x, first appearance inner variable x outer variable x, second appearance

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test07.xml0000644000175000017500000000047410050234363023553 0ustar tseavertseaver
Top Left Top Right
Bottom left Bottom Right
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test13.html0000644000175000017500000000014010050234363023702 0ustar tseavertseaverHere's a stray greater than: > Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test08.xml0000644000175000017500000000476110050234363023557 0ustar tseavertseaver

Some headline

This is the real contents of the bottom right slot.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test_metal2.html0000644000175000017500000000021010050234363025000 0ustar tseavertseaver
OUTER INNER OUTER
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test09.xml0000644000175000017500000000072210050234363023551 0ustar tseavertseaver

Just a bunch of text.

more text...

  • first item
  • second item
    1. second list, first item
    2. second list, second item
      term 1
      term 2
      definition
  • Now let's have a paragraph...

    My Paragraph

  • And a table in a list item:
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test05.html0000644000175000017500000000022210050234363023704 0ustar tseavertseaver

This is the body of test5

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test15.html0000644000175000017500000000101410050234363023705 0ustar tseavertseaver INNERSLOT inner-argument
OUTERSLOT
outer-argument
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test_metal4.html0000755000175000017500000000027310050234363025016 0ustar tseavertseaver Z3 UI Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test07.html0000644000175000017500000000044510050234363023715 0ustar tseavertseaver
Top Left Top Right
Bottom left Bottom Right
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test17.html0000644000175000017500000000032410050234363023712 0ustar tseavertseaverNo No Yes No Yes Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test_metal6.html0000755000175000017500000000022010050234363025010 0ustar tseavertseaver Z3 UI Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test09.html0000644000175000017500000000063310050234363023716 0ustar tseavertseaver

Just a bunch of text.

more text...

  • first item
  • second item
    1. second list, first item
    2. second list, second item
      term 1
      term 2
      definition
  • Now let's have a paragraph...

    My Paragraph

  • And a table in a list item:
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test19.html0000644000175000017500000000113710050234363023717 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test29.html0000644000175000017500000000025310050234363023716 0ustar tseavertseaver
At the tone the time will be 2:32 pm... beep!
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/input/test_failed_attr_translation.html0000644000175000017500000000010210050234363030510 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/0000755000175000017500000000000010447233607022111 5ustar tseavertseaverZope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_metal1.html0000644000175000017500000000272310050234363025213 0ustar tseavertseaver AAA INNER BBB AAA INNER BBB INNER AAA INNER BBB AAA INNER BBB INNER AAA OUTERSLOT BBB AAA INNER INNERSLOT BBB AAA INNER INNERSLOT BBB AAA OUTERSLOT BBB INNER INNERSLOT INNER INNERSLOT INNER INSLOT INSLOT Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test10.html0000644000175000017500000000475210050234363024115 0ustar tseavertseaver
Top Left Top Right
Bottom left

Some headline

This is the real contents of the bottom right slot.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test11.xml0000644000175000017500000000014010050234363023735 0ustar tseavertseaver bar

bad boy!

x undefined

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test14.xml0000644000175000017500000000024610050234363023747 0ustar tseavertseaver
car bike broomstick

Harry Ron Hermione

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test02.html0000644000175000017500000000715610050234363024117 0ustar tseavertseaver sample1 a simple invoice
01786 2000-03-17 55377 2000-03-15 GJ03405 DAVE 1 2000-03-17 K5211(34) 23 23
SHIPWRIGHT RESTAURANTS LIMITED 125 NORTH SERVICE ROAD W WESTLAKE ACCESS NORTH BAY L8B1O5 ONTARIO CANADA ATTN: PAULINE DEGRASSI 1 CS DM 5309 #1013 12 OZ.MUNICH STEIN 37.72 37.72 6 DZ ON 6420 PROVINCIAL DINNER FORK 17.98 107.88 72 EA JR20643 PLASTIC HANDLED STEAK KNIFE .81 58.32 6 DZ ON 6410 PROVINCIAL TEASPOONS 12.16 72.96 0 DZ ON 6411 PROVINCIAL RD BOWL SPOON 6 17.98 0.00 1 EA DO 3218 34 OZ DUAL DIAL SCALE AM3218 70.00 5.0 66.50 1 CS DM 195 20 OZ.BEER PUB GLASS 55.90 55.90 399.28 3.50 23.75 29.61 33.84 33.84 486.48 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test20.html0000644000175000017500000000002610050234363024104 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test16.xml0000644000175000017500000000013610050234363023747 0ustar tseavertseaver bar Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test12.html0000644000175000017500000000045010050234363024106 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test04.html0000644000175000017500000000063110050234363024110 0ustar tseavertseaver
  • 0 hello world
  • 1 hello world
  • 0 goodbye cruel world
  • 1 goodbye cruel world

define-slot

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test17.xml0000644000175000017500000000007210050234363023747 0ustar tseavertseaver Yes Yes Yes Yes Yes Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test14.html0000644000175000017500000000017610050234363024115 0ustar tseavertseaver
car bike broomstick

Harry Ron Hermione

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test18.xml0000644000175000017500000000014710050234363023753 0ustar tseavertseaver Content Content

Content

Yes Yes Yes Yes Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test36.html0000644000175000017500000000010510075023435024114 0ustar tseavertseaver<foo> <foo> some text Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_metal3.html0000644000175000017500000000011410050234363025205 0ustar tseavertseaverShould not get attr in metal Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test06.html0000644000175000017500000000011310050234363024105 0ustar tseavertseaver

This is the body of test5

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test34.html0000644000175000017500000000012310050234363024107 0ustar tseavertseaver stuff foobar more stuff STUFF foobar MORE STUFF Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_metal5.html0000755000175000017500000000026110050234363025215 0ustar tseavertseaver Z3 UI Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test16.html0000644000175000017500000000012610050234363024112 0ustar tseavertseaverblah, blah Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test08.html0000644000175000017500000000466410050234363024126 0ustar tseavertseaver
Top Left Top Right
Bottom left

Some headline

This is the real contents of the bottom right slot.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test18.html0000644000175000017500000000010410050234363024110 0ustar tseavertseaverContent Content

Content

Yes Yes Yes Yes Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_metal7.html0000755000175000017500000000027310050234363025222 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test01.xml0000644000175000017500000000173010050234363023742 0ustar tseavertseaver dadada

This Is The Replaced Title

 &HarryPotter; here/id

5

honda

subaru

acura

foo bar

  • honda
    •
  • subaru
    •
  • acura
    •
python python  

Header Level 3

 

Header Level 3

 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test02.xml0000644000175000017500000000720010050234363023741 0ustar tseavertseaver sample1 a simple invoice
01786 2000-03-17 55377 2000-03-15 GJ03405 DAVE 1 2000-03-17 K5211(34) 23 23
SHIPWRIGHT RESTAURANTS LIMITED 125 NORTH SERVICE ROAD W WESTLAKE ACCESS NORTH BAY L8B1O5 ONTARIO CANADA ATTN: PAULINE DEGRASSI 1 CS DM 5309 #1013 12 OZ.MUNICH STEIN 37.72 37.72 6 DZ ON 6420 PROVINCIAL DINNER FORK 17.98 107.88 72 EA JR20643 PLASTIC HANDLED STEAK KNIFE .81 58.32 6 DZ ON 6410 PROVINCIAL TEASPOONS 12.16 72.96 0 DZ ON 6411 PROVINCIAL RD BOWL SPOON 6 17.98 0.00 1 EA DO 3218 34 OZ DUAL DIAL SCALE AM3218 70.00 5.0 66.50 1 CS DM 195 20 OZ.BEER PUB GLASS 55.90 55.90 399.28 3.50 23.75 29.61 33.84 33.84 486.48 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test03.xml0000644000175000017500000000027710050234363023751 0ustar tseavertseaver

hello brave new world goodbye cruel world hello brave new world

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test04.xml0000644000175000017500000000065610050234363023753 0ustar tseavertseaver
  • 0 hello world
  • 1 hello world
  • 0 goodbye cruel world
  • 1 goodbye cruel world

define-slot

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test01.html0000644000175000017500000000170310050234363024106 0ustar tseavertseaver dadada

This Is The Replaced Title

 &HarryPotter; here/id

5

honda

subaru

acura

foo bar

  • honda
    •
  • subaru
    •
  • acura
    •
python python  

Header Level 3

 

Header Level 3

 Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test05.xml0000644000175000017500000000014410050234363023744 0ustar tseavertseaver

This is the body of test5

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test11.html0000644000175000017500000000014010050234363024101 0ustar tseavertseaver bar

bad boy!

x undefined

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test06.xml0000644000175000017500000000014210050234363023743 0ustar tseavertseaver

This is the body of test5

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test03.html0000644000175000017500000000025010050234363024104 0ustar tseavertseaver

hello brave new world goodbye cruel world hello brave new world

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test07.xml0000644000175000017500000000033010050234363023743 0ustar tseavertseaver
Top Left Top Right
Bottom left Bottom Right
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test13.html0000644000175000017500000000014010050234363024103 0ustar tseavertseaverHere's a stray greater than: > Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test08.xml0000644000175000017500000000471310050234363023755 0ustar tseavertseaver
Top Left Top Right
Bottom left

Some headline

This is the real contents of the bottom right slot.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.

It is supposed to contain a lot of text. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb. Blah, blah, blab. Blabber, blabber, blah. Baah, baah, barb.
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_metal2.html0000644000175000017500000000026310050234363025211 0ustar tseavertseaver
OUTER INNER OUTER
OUTER INNER OUTER
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test09.xml0000644000175000017500000000072210050234363023752 0ustar tseavertseaver

Just a bunch of text.

more text...

  • first item
  • second item
    1. second list, first item
    2. second list, second item
      term 1
      term 2
      definition
  • Now let's have a paragraph...

    My Paragraph

  • And a table in a list item:
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test05.html0000644000175000017500000000011510050234363024106 0ustar tseavertseaver

This is the body of test5

Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test15.html0000644000175000017500000000040510050234363024111 0ustar tseavertseaver INNERSLOT inner-argument
OUTERSLOT
outer-argument
OUTERSLOT
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_metal4.html0000755000175000017500000000027310050234363025217 0ustar tseavertseaver Z3 UI Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test07.html0000644000175000017500000000030110050234363024105 0ustar tseavertseaver
Top Left Top Right
Bottom left Bottom Right
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test17.html0000644000175000017500000000002510050234363024111 0ustar tseavertseaverYes Yes Yes Yes Yes Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_metal6.html0000755000175000017500000000022010050234363025211 0ustar tseavertseaver Z3 UI Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test09.html0000644000175000017500000000071710050234363024122 0ustar tseavertseaver

Just a bunch of text.

more text...

  • first item
  • second item
    1. second list, first item
    2. second list, second item
      term 1
      term 2
      definition
  • Now let's have a paragraph...

    My Paragraph

  • And a table in a list item:
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test19.html0000644000175000017500000000040610050234363024116 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test29.html0000644000175000017500000000010710050234363024115 0ustar tseavertseaver
AT THE TONE THE TIME WILL BE 59 MINUTES AFTER 6 PM... BEEP!
Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/output/test_failed_attr_translation.html0000644000175000017500000000004310050234363030715 0ustar tseavertseaver Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/utils.py0000644000175000017500000000334210303203042022242 0ustar tseavertseaver"""Helper functions for the test suite.""" import os import sys mydir = os.path.abspath(os.path.dirname(__file__)) codedir = os.path.dirname(os.path.dirname(mydir)) if codedir not in sys.path: sys.path.append(codedir) import unittest import xml.parsers.expat # Set skipxml to true if an XML parser could not be found. # (But Python always includes one now.) skipxml = False # Set oldexpat if the StartDoctypeDeclHandler and XmlDeclHandler are # not supported. The tests need to know whether the events reported # by those handlers should be expected, but need to make sure the # right thing is returned if they are. # oldexpat = False p = xml.parsers.expat.ParserCreate() # # Can't use hasattr() since pyexpat supports the handler # attributes in a broken way. try: p.StartDoctypeDeclHandler = None except AttributeError: oldexpat = True def run_suite(suite, outf=None, errf=None): if outf is None: outf = sys.stdout runner = unittest.TextTestRunner(outf) result = runner.run(suite) ## print "\n\n" ## if result.errors: ## print "Errors (unexpected exceptions):" ## map(print_error, result.errors) ## print ## if result.failures: ## print "Failures (assertion failures):" ## map(print_error, result.failures) ## print newerrs = len(result.errors) + len(result.failures) if newerrs: print "'Errors' indicate exceptions other than AssertionError." print "'Failures' indicate AssertionError" if errf is None: errf = sys.stderr errf.write("%d errors, %d failures\n" % (len(result.errors), len(result.failures))) return newerrs def print_error(info): testcase, (type, e, tb) = info Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/test_xmlparser.py0000755000175000017500000001751310050234363024177 0ustar tseavertseaver#! /usr/bin/env python1.5 """Tests for XMLParser.py.""" import string import sys from TAL.tests import utils import unittest from TAL import XMLParser class EventCollector(XMLParser.XMLParser): def __init__(self): self.events = [] self.append = self.events.append XMLParser.XMLParser.__init__(self) self.parser.ordered_attributes = 1 def get_events(self): # Normalize the list of events so that buffer artefacts don't # separate runs of contiguous characters. L = [] prevtype = None for event in self.events: type = event[0] if type == prevtype == "data": L[-1] = ("data", L[-1][1] + event[1]) else: L.append(event) prevtype = type self.events = L return L # structure markup def StartElementHandler(self, tag, attrs): self.append(("starttag", tag, attrs)) def EndElementHandler(self, tag): self.append(("endtag", tag)) # all other markup def CommentHandler(self, data): self.append(("comment", data)) def handle_charref(self, data): self.append(("charref", data)) def CharacterDataHandler(self, data): self.append(("data", data)) def StartDoctypeDeclHandler(self, rootelem, publicId, systemId, subset): self.append(("doctype", rootelem, systemId, publicId, subset)) def XmlDeclHandler(self, version, encoding, standalone): self.append(("decl", version, encoding, standalone)) def ExternalEntityRefHandler(self, data): self.append(("entityref", data)) def ProcessingInstructionHandler(self, target, data): self.append(("pi", target, data)) class EventCollectorExtra(EventCollector): def handle_starttag(self, tag, attrs): EventCollector.handle_starttag(self, tag, attrs) self.append(("starttag_text", self.get_starttag_text())) class SegmentedFile: def __init__(self, parts): self.parts = list(parts) def read(self, bytes): if self.parts: s = self.parts.pop(0) else: s = '' return s class XMLParserTestCase(unittest.TestCase): def _run_check(self, source, events, collector=EventCollector): parser = collector() if isinstance(source, type([])): parser.parseStream(SegmentedFile(source)) else: parser.parseString(source) if utils.oldexpat: while events[0][0] in ('decl', 'doctype'): del events[0] self.assertEquals(parser.get_events(), events) def _run_check_extra(self, source, events): self._run_check(source, events, EventCollectorExtra) def _parse_error(self, source): def parse(source=source): parser = XMLParser.XMLParser() parser.parseString(source) self.assertRaises(XMLParser.XMLParseError, parse) def check_processing_instruction_plus(self): self._run_check("", [ ("pi", "processing", "instruction"), ("starttag", "a", []), ("endtag", "a"), ]) def _check_simple_html(self): self._run_check("""\ &entity; sample text """, [ ("decl", "1.0", "iso-8859-1", -1), ("doctype", "html", "foo", "bar", 0), ("starttag", "html", []), # ("entityref", "entity"), ("data", " \n"), ("comment", "comment1a\n-><", [ ("starttag", "a", []), ("starttag", "b", []), ("endtag", "a"), ("endtag", "b"), ]) except: e = sys.exc_info()[1] self.assert_(e.lineno == 1, "did not receive correct position information") else: self.fail("expected parse error: bad nesting") def check_attr_syntax(self): output = [ ("starttag", "a", ["b", "v", "c", "v"]), ("endtag", "a"), ] self._run_check("""""", output) self._run_check("""""", output) self._run_check("""""", output) self._run_check("""""", output) def check_attr_values(self): self._run_check("""""", [("starttag", "a", ["b", "xxx xxx", "c", "yyy yyy", "d", " xyz "]), ("endtag", "a"), ]) self._run_check("""""", [ ("starttag", "a", ["b", "", "c", "", "d", ""]), ("endtag", "a"), ]) def check_attr_entity_replacement(self): self._run_check("""""", [ ("starttag", "a", ["b", "&><\"'"]), ("endtag", "a"), ]) def check_attr_funky_names(self): self._run_check("""""", [ ("starttag", "a", ["a.b", "v", "e-f", "v"]), ("endtag", "a"), ]) def check_starttag_end_boundary(self): self._run_check("""""", [ ("starttag", "a", ["b", "<"]), ("endtag", "a"), ]) self._run_check("""""", [ ("starttag", "a", ["b", ">"]), ("endtag", "a"), ]) def check_buffer_artefacts(self): output = [("starttag", "a", ["b", "<"]), ("endtag", "a")] self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) output = [("starttag", "a", ["b", ">"]), ("endtag", "a")] self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) self._run_check([""], output) def check_starttag_junk_chars(self): self._parse_error("<") self._parse_error("<>") self._parse_error("") self._parse_error("") self._parse_error("") self._parse_error("") self._parse_error("<$") self._parse_error("<$>") self._parse_error("") self._parse_error("'") self._parse_error("
page1=
''' main_template = ''' main_template=
main_template=
main_template= ''' footer = '''
footer=
''' expected = ''' main_template=main_template (2,14)
page1=page1 (3,6)
main_template=main_template (4,14)
footer=footer (2,7)
main_template=main_template (6,14) ''' class Tests(unittest.TestCase): def parse(self, eng, s, fn): gen = TALGenerator(expressionCompiler=eng, xml=0, source_file=fn) parser = HTMLTALParser(gen) parser.parseString(s) program, macros = parser.getCode() return program, macros def testSourcePositions(self): """Ensure source file and position are set correctly by TAL""" macros = {} eng = DummyEngine(macros) page1_program, page1_macros = self.parse(eng, page1, 'page1') main_template_program, main_template_macros = self.parse( eng, main_template, 'main_template') footer_program, footer_macros = self.parse(eng, footer, 'footer') macros['main'] = main_template_macros['main'] macros['foot'] = footer_macros['foot'] stream = StringIO() interp = TALInterpreter(page1_program, macros, eng, stream) interp() self.assertEqual(stream.getvalue().strip(), expected.strip(), stream.getvalue()) def test_suite(): suite = unittest.TestSuite() suite.addTest(unittest.makeSuite(Tests)) return suite if __name__ == "__main__": unittest.main() Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/test_files.py0000755000175000017500000000356510050234363023266 0ustar tseavertseaver#! /usr/bin/env python1.5 """Tests that run driver.py over input files comparing to output files.""" import os import sys import glob from TAL.tests import utils import unittest from TAL import runtest class FileTestCase(unittest.TestCase): def __init__(self, file, dir): self.__file = file self.__dir = dir unittest.TestCase.__init__(self) def shortDescription(self): return os.path.join("...", "TAL", "tests", "input", os.path.basename(self.__file)) def runTest(self): basename = os.path.basename(self.__file) #sys.stdout.write(basename + " ") sys.stdout.flush() if basename[:10] == 'test_metal': sys.argv = ["", "-Q", "-m", self.__file] else: sys.argv = ["", "-Q", self.__file] pwd = os.getcwd() try: try: os.chdir(self.__dir) runtest.main() finally: os.chdir(pwd) except SystemExit, what: if what.code: self.fail("output for %s didn't match" % self.__file) try: script = __file__ except NameError: script = sys.argv[0] def test_suite(): suite = unittest.TestSuite() dir = os.path.dirname(script) dir = os.path.abspath(dir) parentdir = os.path.dirname(dir) prefix = os.path.join(dir, "input", "test*.") if utils.skipxml: xmlargs = [] else: xmlargs = glob.glob(prefix + "xml") xmlargs.sort() htmlargs = glob.glob(prefix + "html") htmlargs.sort() args = xmlargs + htmlargs if not args: sys.stderr.write("Warning: no test input files found!!!\n") for arg in args: case = FileTestCase(arg, parentdir) suite.addTest(case) return suite if __name__ == "__main__": errs = utils.run_suite(test_suite()) sys.exit(errs and 1 or 0) Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/run.py0000755000175000017500000000135710050234363021726 0ustar tseavertseaver#! /usr/bin/env python1.5 """Run all tests.""" import sys import utils import unittest import test_htmlparser import test_htmltalparser import test_talinterpreter import test_files import test_sourcepos def test_suite(): suite = unittest.TestSuite() suite.addTest(test_htmlparser.test_suite()) suite.addTest(test_htmltalparser.test_suite()) if not utils.skipxml: import test_xmlparser suite.addTest(test_xmlparser.test_suite()) suite.addTest(test_talinterpreter.test_suite()) suite.addTest(test_files.test_suite()) suite.addTest(test_sourcepos.test_suite()) return suite def main(): return utils.run_suite(test_suite()) if __name__ == "__main__": errs = main() sys.exit(errs and 1 or 0) Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/test_htmltalparser.py0000755000175000017500000010243410337373524025054 0ustar tseavertseaver#! /usr/bin/env python ############################################################################## # # Copyright (c) 2001, 2002 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Tests for the HTMLTALParser code generator.""" import pprint import sys from TAL.tests import utils import unittest from TAL import HTMLTALParser from TAL.TALDefs import TAL_VERSION, TALError, METALError class TestCaseBase(unittest.TestCase): prologue = "" epilogue = "" initial_program = [('version', TAL_VERSION), ('mode', 'html')] final_program = [] def _merge(self, p1, p2): if p1 and p2: op1, args1 = p1[-1] op2, args2 = p2[0] if op1.startswith('rawtext') and op2.startswith('rawtext'): return (p1[:-1] + [rawtext(args1[0] + args2[0])] + p2[1:]) return p1+p2 def _run_check(self, source, program, macros={}): parser = HTMLTALParser.HTMLTALParser() parser.parseString(self.prologue + source + self.epilogue) got_program, got_macros = parser.getCode() program = self._merge(self.initial_program, program) program = self._merge(program, self.final_program) self.assert_(got_program == program, "Program:\n" + pprint.pformat(got_program) + "\nExpected:\n" + pprint.pformat(program)) self.assert_(got_macros == macros, "Macros:\n" + pprint.pformat(got_macros) + "\nExpected:\n" + pprint.pformat(macros)) def _get_check(self, source, program=[], macros={}): parser = HTMLTALParser.HTMLTALParser() parser.parseString(source) got_program, got_macros = parser.getCode() pprint.pprint(got_program) pprint.pprint(got_macros) def _should_error(self, source, exc=TALError): def parse(self=self, source=source): parser = HTMLTALParser.HTMLTALParser() parser.parseString(self.prologue + source + self.epilogue) self.assertRaises(exc, parse) def rawtext(s): """Compile raw text to the appropriate instruction.""" if "\n" in s: return ("rawtextColumn", (s, len(s) - (s.rfind("\n") + 1))) else: return ("rawtextOffset", (s, len(s))) class HTMLTALParserTestCases(TestCaseBase): def check_code_simple_identity(self): self._run_check("""My Title</html>""", [ rawtext('<html a="b" b="c" c="d">' '<title>My Title'), ]) def check_code_implied_list_closings(self): self._run_check("""

""", [ rawtext('

'), ]) self._run_check("""
""", [ rawtext('
' '
'), ]) def check_code_implied_table_closings(self): self._run_check("""

text \n') def visit_field_body(self, node): self.body.append(self.starttag(node, 'td', '', CLASS='field-body')) self.set_first_last(node) def depart_field_body(self, node): self.body.append('\n') def visit_field_list(self, node): self.body.append(self.starttag(node, 'table', frame='void', rules='none', CLASS='docutils field-list')) self.body.append('\n' '\n' '\n') def depart_field_list(self, node): self.body.append('\n
head\t
cell\t""" """""", [ rawtext('

text

cell \n \t \n
' '\t
head
cell\t' ' \n \t \n
cell
'), ]) self._run_check("""
cell """ """
cell
""", [ rawtext('
cell ' '
cell
'), ]) def check_code_bad_nesting(self): def check(self=self): self._run_check("", []) self.assertRaises(HTMLTALParser.NestingError, check) def check_code_attr_syntax(self): output = [ rawtext(''), ] self._run_check("""""", output) self._run_check("""""", output) self._run_check("""""", output) self._run_check("""""", output) def check_code_attr_values(self): self._run_check( """""", [ rawtext('')]) self._run_check("""""", [ rawtext(''), ]) def check_code_attr_entity_replacement(self): # we expect entities *not* to be replaced by HTLMParser! self._run_check("""""", [ rawtext(''), ]) self._run_check("""""", [ rawtext(''), ]) self._run_check("""""", [ rawtext(''), ]) self._run_check("""""", [ rawtext(''), ]) def check_code_attr_funky_names(self): self._run_check("""""", [ rawtext(''), ]) def check_code_pcdata_entityref(self): self._run_check(""" """, [ rawtext(' '), ]) def check_code_short_endtags(self): self._run_check("""""", [ rawtext(''), ]) class METALGeneratorTestCases(TestCaseBase): def check_null(self): self._run_check("", []) def check_define_macro(self): macro = self.initial_program + [ ('startTag', ('p', [('metal:define-macro', 'M', 'metal')])), rawtext('booh

'), ] program = [ ('setPosition', (1, 0)), ('defineMacro', ('M', macro)), ] macros = {'M': macro} self._run_check('

booh

', program, macros) def check_use_macro(self): self._run_check('

booh

', [ ('setPosition', (1, 0)), ('useMacro', ('M', '$M$', {}, [('startTag', ('p', [('metal:use-macro', 'M', 'metal')])), rawtext('booh

')])), ]) def check_define_slot(self): macro = self.initial_program + [ ('startTag', ('p', [('metal:define-macro', 'M', 'metal')])), rawtext('foo'), ('setPosition', (1, 29)), ('defineSlot', ('S', [('startTag', ('span', [('metal:define-slot', 'S', 'metal')])), rawtext('spam')])), rawtext('bar

'), ] program = [('setPosition', (1, 0)), ('defineMacro', ('M', macro))] macros = {'M': macro} self._run_check('

foo' 'spambar

', program, macros) def check_fill_slot(self): self._run_check('

foo' 'spambar

', [ ('setPosition', (1, 0)), ('useMacro', ('M', '$M$', {'S': [('startTag', ('span', [('metal:fill-slot', 'S', 'metal')])), rawtext('spam')]}, [('startTag', ('p', [('metal:use-macro', 'M', 'metal')])), rawtext('foo'), ('setPosition', (1, 26)), ('fillSlot', ('S', [('startTag', ('span', [('metal:fill-slot', 'S', 'metal')])), rawtext('spam')])), rawtext('bar

')])), ]) class TALGeneratorTestCases(TestCaseBase): def check_null(self): self._run_check("", []) def check_define_1(self): self._run_check("

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:define': 'xyzzy string:spam'}), ('setLocal', ('xyzzy', '$string:spam$')), ('startTag', ('p', [('tal:define', 'xyzzy string:spam', 'tal')])), ('endScope', ()), rawtext('

'), ]) def check_define_2(self): self._run_check("

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:define': 'local xyzzy string:spam'}), ('setLocal', ('xyzzy', '$string:spam$')), ('startTag', ('p', [('tal:define', 'local xyzzy string:spam', 'tal')])), ('endScope', ()), rawtext('

'), ]) def check_define_3(self): self._run_check("

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:define': 'global xyzzy string:spam'}), ('setGlobal', ('xyzzy', '$string:spam$')), ('startTag', ('p', [('tal:define', 'global xyzzy string:spam', 'tal')])), ('endScope', ()), rawtext('

'), ]) def check_define_4(self): self._run_check("

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:define': 'x string:spam; y x'}), ('setLocal', ('x', '$string:spam$')), ('setLocal', ('y', '$x$')), ('startTag', ('p', [('tal:define', 'x string:spam; y x', 'tal')])), ('endScope', ()), rawtext('

'), ]) def check_define_5(self): self._run_check("

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:define': 'x string:;;;;; y x'}), ('setLocal', ('x', '$string:;;$')), ('setLocal', ('y', '$x$')), ('startTag', ('p', [('tal:define', 'x string:;;;;; y x', 'tal')])), ('endScope', ()), rawtext('

'), ]) def check_define_6(self): self._run_check( "

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:define': 'x string:spam; global y x; local z y'}), ('setLocal', ('x', '$string:spam$')), ('setGlobal', ('y', '$x$')), ('setLocal', ('z', '$y$')), ('startTag', ('p', [('tal:define', 'x string:spam; global y x; local z y', 'tal')])), ('endScope', ()), rawtext('

'), ]) def check_condition(self): self._run_check( "

foo

", [ rawtext('

'), ('setPosition', (1, 3)), ('beginScope', {'tal:condition': 'python:1'}), ('condition', ('$python:1$', [('startTag', ('span', [('tal:condition', 'python:1', 'tal')])), rawtext('foo')])), ('endScope', ()), rawtext('

'), ]) def check_content_1(self): self._run_check("

bar

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:content': 'string:foo'}), ('startTag', ('p', [('tal:content', 'string:foo', 'tal')])), ('insertText', ('$string:foo$', [rawtext('bar')])), ('endScope', ()), rawtext('

'), ]) def check_content_2(self): self._run_check("

bar

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:content': 'text string:foo'}), ('startTag', ('p', [('tal:content', 'text string:foo', 'tal')])), ('insertText', ('$string:foo$', [rawtext('bar')])), ('endScope', ()), rawtext('

'), ]) def check_content_3(self): self._run_check("

bar

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:content': 'structure string:
'}), ('startTag', ('p', [('tal:content', 'structure string:
', 'tal')])), ('insertStructure', ('$string:
$', {}, [rawtext('bar')])), ('endScope', ()), rawtext('

'), ]) def check_replace_1(self): self._run_check("

bar

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:replace': 'string:foo'}), ('insertText', ('$string:foo$', [('startTag', ('p', [('tal:replace', 'string:foo', 'tal')])), rawtext('bar

')])), ('endScope', ()), ]) def check_replace_2(self): self._run_check("

bar

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:replace': 'text string:foo'}), ('insertText', ('$string:foo$', [('startTag', ('p', [('tal:replace', 'text string:foo', 'tal')])), rawtext('bar

')])), ('endScope', ()), ]) def check_replace_3(self): self._run_check("

bar

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:replace': 'structure string:
'}), ('insertStructure', ('$string:
$', {}, [('startTag', ('p', [('tal:replace', 'structure string:
', 'tal')])), rawtext('bar

')])), ('endScope', ()), ]) def check_repeat(self): self._run_check("

" "dummy

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:repeat': 'x python:(1,2,3)'}), ('loop', ('x', '$python:(1,2,3)$', [('startTag', ('p', [('tal:repeat', 'x python:(1,2,3)', 'tal')])), ('setPosition', (1, 33)), ('beginScope', {'tal:replace': 'x'}), ('insertText', ('$x$', [('startTag', ('span', [('tal:replace', 'x', 'tal')])), rawtext('dummy')])), ('endScope', ()), rawtext('

')])), ('endScope', ()), ]) def check_attributes_1(self): self._run_check("" "link", [ ('setPosition', (1, 0)), ('beginScope', {'tal:attributes': 'href string:http://www.zope.org; x string:y', 'name': 'bar', 'href': 'foo'}), ('startTag', ('a', [('href', 'foo', 'replace', '$string:http://www.zope.org$', 0, None), ('name', 'name="bar"'), ('tal:attributes', 'href string:http://www.zope.org; x string:y', 'tal'), ('x', None, 'insert', '$string:y$', 0, None)])), ('endScope', ()), rawtext('link'), ]) def check_attributes_2(self): self._run_check("

duh

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:attributes': 'src string:foo.png', 'tal:replace': 'structure string:'}), ('insertStructure', ('$string:$', {'src': ('$string:foo.png$', 0, None)}, [('startTag', ('p', [('tal:replace', 'structure string:', 'tal'), ('tal:attributes', 'src string:foo.png', 'tal')])), rawtext('duh

')])), ('endScope', ()), ]) def check_on_error_1(self): self._run_check("

okay

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:content': 'notHere', 'tal:on-error': 'string:error'}), ('onError', ([('startTag', ('p', [('tal:on-error', 'string:error', 'tal'), ('tal:content', 'notHere', 'tal')])), ('insertText', ('$notHere$', [rawtext('okay')])), rawtext('

')], [('startTag', ('p', [('tal:on-error', 'string:error', 'tal'), ('tal:content', 'notHere', 'tal')])), ('insertText', ('$string:error$', [])), rawtext('

')])), ('endScope', ()), ]) def check_on_error_2(self): self._run_check("

okay

", [ ('setPosition', (1, 0)), ('beginScope', {'tal:replace': 'notHere', 'tal:on-error': 'string:error'}), ('onError', ([('insertText', ('$notHere$', [('startTag', ('p', [('tal:on-error', 'string:error', 'tal'), ('tal:replace', 'notHere', 'tal')])), rawtext('okay

')]))], [('startTag', ('p', [('tal:on-error', 'string:error', 'tal'), ('tal:replace', 'notHere', 'tal')])), ('insertText', ('$string:error$', [])), rawtext('

')])), ('endScope', ()), ]) def check_dup_attr(self): self._should_error("") self._should_error("", METALError) def check_tal_errors(self): self._should_error("

") self._should_error("

") self._should_error("

") self._should_error("

") self._should_error("

") for tag in HTMLTALParser.EMPTY_HTML_TAGS: self._should_error("<%s tal:content='string:foo'>" % tag) def check_metal_errors(self): exc = METALError self._should_error(2*"

xxx

", exc) self._should_error("" + 2*"

" + "", exc) self._should_error("

", exc) self._should_error("

", exc) # # I18N test cases # def check_i18n_attributes(self): self._run_check("foo", [ ('setPosition', (1, 0)), ('beginScope', {'alt': 'foo', 'i18n:attributes': 'alt'}), ('startTag', ('img', [('alt', 'foo', 'replace', None, 1, None), ('i18n:attributes', 'alt', 'i18n')])), ('endScope', ()), ]) self._run_check("foo", [ ('setPosition', (1, 0)), ('beginScope', {'alt': 'foo', 'i18n:attributes': 'alt foo ; bar'}), ('startTag', ('img', [('alt', 'foo', 'replace', None, 1, 'foo'), ('i18n:attributes', 'alt foo ; bar', 'i18n'), ('bar', None, 'insert', None, 1, None)])), ('endScope', ()), ]) self._should_error('''''') def test_i18n_name_bad_name(self): self._should_error("") self._should_error("") def test_i18n_attributes_repeated_attr(self): self._should_error("") self._should_error("") def check_i18n_translate(self): # input/test19.html self._run_check('''\ Replace this This is a translated string And another translated string ''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': ''}), ('startTag', ('span', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextOffset', ('Replace this', 12))])), ('rawtextBeginScope', ('\n', 0, (2, 0), 1, {'i18n:translate': 'msgid'})), ('startTag', ('span', [('i18n:translate', 'msgid', 'i18n')])), ('insertTranslation', ('msgid', [('rawtextColumn', ('This is a\ntranslated string', 17))])), ('rawtextBeginScope', ('\n', 0, (4, 0), 1, {'i18n:translate': ''})), ('startTag', ('span', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextColumn', ('And another\ntranslated string', 17))])), ('endScope', ()), ('rawtextColumn', ('\n', 0))]) def check_i18n_translate_with_nested_tal(self): self._run_check('''\ replaceable

content

''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': ''}), ('startTag', ('span', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextOffset', ('replaceable ', 12)), ('setPosition', (1, 36)), ('beginScope', {'tal:replace': 'str:here'}), ('insertText', ('$str:here$', [('startTag', ('p', [('tal:replace', 'str:here', 'tal')])), ('rawtextOffset', ('content

', 11))])), ('endScope', ())])), ('endScope', ()), ('rawtextColumn', ('\n', 0)) ]) def check_i18n_name(self): # input/test21.html self._run_check('''\ was born in . ''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': ''}), ('startTag', ('span', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextBeginScope', ('\n ', 2, (2, 2), 0, {'i18n:name': 'name', 'tal:replace': 'str:Lomax'})), ('i18nVariable', ('name', [('startEndTag', ('span', [('tal:replace', 'str:Lomax', 'tal'), ('i18n:name', 'name', 'i18n')]))], '$str:Lomax$', 0)), ('rawtextBeginScope', (' was born in\n ', 2, (3, 2), 1, {'i18n:name': 'country', 'tal:replace': 'str:Antarctica'})), ('i18nVariable', ('country', [('startEndTag', ('span', [('tal:replace', 'str:Antarctica', 'tal'), ('i18n:name', 'country', 'i18n')]))], '$str:Antarctica$', 0)), ('endScope', ()), ('rawtextColumn', ('.\n', 0))])), ('endScope', ()), ('rawtextColumn', ('\n', 0)) ]) def test_i18n_name_with_content(self): self._run_check('
This is text for ' '.' '
', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': ''}), ('startTag', ('div', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextOffset', ('This is text for ', 17)), ('setPosition', (1, 40)), ('beginScope', {'tal:content': 'bar', 'i18n:name': 'bar_name', 'i18n:translate': ''}), ('i18nVariable', ('bar_name', [('startTag', ('span', [('i18n:translate', '', 'i18n'), ('tal:content', 'bar', 'tal'), ('i18n:name', 'bar_name', 'i18n')])), ('insertTranslation', ('', [('insertText', ('$bar$', []))])), ('rawtextOffset', ('', 7))], None, 0)), ('endScope', ()), ('rawtextOffset', ('.', 1))])), ('endScope', ()), ('rawtextOffset', ('', 6)) ]) def check_i18n_name_implicit_value(self): # input/test22.html self._run_check('''\ Jim was born in the USA. ''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': ''}), ('startTag', ('span', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextBeginScope', ('\n ', 2, (2, 2), 0, {'i18n:name': 'name'})), ('i18nVariable', ('name', [('rawtextOffset', ('Jim', 10))], None, 0)), ('rawtextBeginScope', (' was born in\n ', 2, (3, 2), 1, {'i18n:name': 'country'})), ('i18nVariable', ('country', [('rawtextOffset', ('the USA', 7))], None, 0)), ('endScope', ()), ('rawtextColumn', ('.\n', 0))])), ('endScope', ()), ('rawtextColumn', ('\n', 0)) ]) def check_i18n_context_domain(self): self._run_check("", [ ('setPosition', (1, 0)), ('beginI18nContext', {'domain': 'mydomain', 'source': None, 'target': None}), ('beginScope', {'i18n:domain': 'mydomain'}), ('startEndTag', ('span', [('i18n:domain', 'mydomain', 'i18n')])), ('endScope', ()), ('endI18nContext', ()), ]) def check_i18n_context_source(self): self._run_check("", [ ('setPosition', (1, 0)), ('beginI18nContext', {'source': 'en', 'domain': 'default', 'target': None}), ('beginScope', {'i18n:source': 'en'}), ('startEndTag', ('span', [('i18n:source', 'en', 'i18n')])), ('endScope', ()), ('endI18nContext', ()), ]) def check_i18n_context_source_target(self): self._run_check("", [ ('setPosition', (1, 0)), ('beginI18nContext', {'source': 'en', 'target': 'ru', 'domain': 'default'}), ('beginScope', {'i18n:source': 'en', 'i18n:target': 'ru'}), ('startEndTag', ('span', [('i18n:source', 'en', 'i18n'), ('i18n:target', 'ru', 'i18n')])), ('endScope', ()), ('endI18nContext', ()), ]) def check_i18n_context_in_define_slot(self): text = ("
" "
spam
" "
") self._run_check(text, [ ('setPosition', (1, 0)), ('useMacro', ('M', '$M$', {'S': [('startTag', ('div', [('metal:fill-slot', 'S', 'metal')])), rawtext('spam')]}, [('beginI18nContext', {'domain': 'mydomain', 'source': None, 'target': None}), ('beginScope', {'i18n:domain': 'mydomain', 'metal:use-macro': 'M'}), ('startTag', ('div', [('metal:use-macro', 'M', 'metal'), ('i18n:domain', 'mydomain', 'i18n')])), ('setPosition', (1, 48)), ('fillSlot', ('S', [('startTag', ('div', [('metal:fill-slot', 'S', 'metal')])), rawtext('spam')])), ('endScope', ()), rawtext(''), ('endI18nContext', ())])), ]) def check_i18n_data(self): # input/test23.html self._run_check('''\ 2:32 pm ''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': 'timefmt', 'i18n:data': 'here/currentTime'}), ('startTag', ('span', [('i18n:data', 'here/currentTime', 'i18n'), ('i18n:translate', 'timefmt', 'i18n')])), ('insertTranslation', ('timefmt', [('rawtextOffset', ('2:32 pm', 7))], '$here/currentTime$')), ('endScope', ()), ('rawtextColumn', ('\n', 0)) ]) def check_i18n_data_with_name(self): # input/test29.html self._run_check('''\
At the tone the time will be 2:32 pm... beep!
''', [('setPosition', (1, 0)), ('beginScope', {'i18n:translate': ''}), ('startTag', ('div', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextBeginScope', ('At the tone the time will be\n', 0, (2, 0), 0, {'i18n:data': 'here/currentTime', 'i18n:name': 'time', 'i18n:translate': 'timefmt'})), ('insertTranslation', ('timefmt', [('startTag', ('span', [('i18n:data', 'here/currentTime', 'i18n'), ('i18n:translate', 'timefmt', 'i18n'), ('i18n:name', 'time', 'i18n')])), ('i18nVariable', ('time', [], None, 0))], '$here/currentTime$')), ('endScope', ()), ('rawtextOffset', ('... beep!', 9))])), ('endScope', ()), ('rawtextColumn', ('\n', 0))] ) def check_i18n_explicit_msgid_with_name(self): # input/test26.html self._run_check('''\ Job #NN ''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': 'jobnum'}), ('startTag', ('span', [('i18n:translate', 'jobnum', 'i18n')])), ('insertTranslation', ('jobnum', [('rawtextBeginScope', ('\n Job #', 9, (2, 9), 0, {'i18n:name': 'jobnum', 'tal:replace': 'context/@@object_name'})), ('i18nVariable', ('jobnum', [('startTag', ('span', [('tal:replace', 'context/@@object_name', 'tal'), ('i18n:name', 'jobnum', 'i18n')])), ('rawtextOffset', ('NN', 2)), ('rawtextOffset', ('', 7))], '$context/@@object_name$', 0)), ('endScope', ())])), ('endScope', ()), ('rawtextColumn', ('\n', 0)) ]) def check_i18n_name_around_tal_content(self): # input/test28.html self._run_check('''\

Your contact email address is recorded as user@host.com

''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': 'verify'}), ('startTag', ('p', [('i18n:translate', 'verify', 'i18n')])), ('insertTranslation', ('verify', [('rawtextBeginScope', ('Your contact email address is recorded as\n ', 4, (2, 4), 0, {'i18n:name': 'email'})), ('i18nVariable', ('email', [('rawtextBeginScope', ('\n ', 4, (3, 4), 0, {'href': 'mailto:user@example.com', 'tal:content': 'request/submitter'})), ('startTag', ('a', [('href', 'href="mailto:user@example.com"'), ('tal:content', 'request/submitter', 'tal')])), ('insertText', ('$request/submitter$', [('rawtextOffset', ('user@host.com', 13))])), ('endScope', ()), ('rawtextOffset', ('', 4))], None, 0)), ('endScope', ()), ('rawtextColumn', ('\n', 0))])), ('endScope', ()), ('rawtextColumn', ('

\n', 0)) ]) def check_i18n_name_with_tal_content(self): # input/test27.html self._run_check('''\

Your contact email address is recorded as user@host.com

''', [ ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': 'verify'}), ('startTag', ('p', [('i18n:translate', 'verify', 'i18n')])), ('insertTranslation', ('verify', [('rawtextBeginScope', ('Your contact email address is recorded as\n ', 4, (2, 4), 0, {'href': 'mailto:user@example.com', 'i18n:name': 'email', 'tal:content': 'request/submitter'})), ('i18nVariable', ('email', [('startTag', ('a', [('href', 'href="mailto:user@example.com"'), ('tal:content', 'request/submitter', 'tal'), ('i18n:name', 'email', 'i18n')])), ('insertText', ('$request/submitter$', [('rawtextOffset', ('user@host.com', 13))])), ('rawtextOffset', ('', 4))], None, 0)), ('endScope', ()), ('rawtextColumn', ('\n', 0))])), ('endScope', ()), ('rawtextColumn', ('

\n', 0)) ]) def test_suite(): suite = unittest.TestSuite() suite.addTest(unittest.makeSuite(HTMLTALParserTestCases, "check_")) suite.addTest(unittest.makeSuite(METALGeneratorTestCases, "check_")) suite.addTest(unittest.makeSuite(TALGeneratorTestCases, "check_")) return suite if __name__ == "__main__": errs = utils.run_suite(test_suite()) sys.exit(errs and 1 or 0) Zope-2.9.4-retire_zpkg/lib/python/TAL/tests/test_talinterpreter.py0000644000175000017500000004051610332203276025224 0ustar tseavertseaver# -*- coding: ISO-8859-1 -*- ############################################################################## # # Copyright (c) 2001, 2002 Zope Corporation and Contributors. # All Rights Reserved. # # This software is subject to the provisions of the Zope Public License, # Version 2.1 (ZPL). A copy of the ZPL should accompany this distribution. # THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED # WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED # WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS # FOR A PARTICULAR PURPOSE. # ############################################################################## """Tests for TALInterpreter. $Id: test_talinterpreter.py 39848 2005-11-02 18:34:38Z philikon $ """ import sys import unittest from StringIO import StringIO from TAL.TALDefs import METALError, I18NError from TAL.HTMLTALParser import HTMLTALParser from TAL.TALParser import TALParser from TAL.TALInterpreter import TALInterpreter from TAL.DummyEngine import DummyEngine, DummyTranslationService from TAL.TALInterpreter import interpolate from TAL.tests import utils from zope.i18nmessageid import Message class TestCaseBase(unittest.TestCase): def _compile(self, source): parser = HTMLTALParser() parser.parseString(source) program, macros = parser.getCode() return program, macros class MacroErrorsTestCase(TestCaseBase): def setUp(self): dummy, macros = self._compile('

Booh

') self.macro = macros['M'] self.engine = DummyEngine(macros) program, dummy = self._compile('

Bah

') self.interpreter = TALInterpreter(program, {}, self.engine) def tearDown(self): try: self.interpreter() except METALError: pass else: self.fail("Expected METALError") def test_mode_error(self): self.macro[1] = ("mode", "duh") def test_version_error(self): self.macro[0] = ("version", "duh") class I18NCornerTestCase(TestCaseBase): def setUp(self): self.engine = DummyEngine() self.engine.setLocal('foo', Message('FoOvAlUe', 'default')) self.engine.setLocal('bar', 'BaRvAlUe') self.engine.setLocal('raw', ' \tRaW\n ') self.engine.setLocal('noxlt', Message("don't translate me")) def _check(self, program, expected): result = StringIO() self.interpreter = TALInterpreter(program, {}, self.engine, stream=result) self.interpreter() self.assertEqual(expected, result.getvalue()) def test_simple_messageid_translate(self): # This test is mainly here to make sure our DummyEngine works # correctly. program, macros = self._compile('') self._check(program, 'FOOVALUE\n') program, macros = self._compile('') self._check(program, 'FOOVALUE\n') def test_replace_with_messageid_and_i18nname(self): program, macros = self._compile( '
' '' '
') self._check(program, '
FOOVALUE
\n') def test_pythonexpr_replace_with_messageid_and_i18nname(self): program, macros = self._compile( '
' '' '
') self._check(program, '
FOOVALUE
\n') def test_structure_replace_with_messageid_and_i18nname(self): program, macros = self._compile( '
' '' '
') self._check(program, '
FOOVALUE
\n') def test_complex_replace_with_messageid_and_i18nname(self): program, macros = self._compile( '
' '' '' '' '
') self._check(program, '
FOOVALUE
\n') def test_content_with_messageid_and_i18nname(self): program, macros = self._compile( '
' '' '
') self._check(program, '
FOOVALUE
\n') def test_content_with_messageid_and_i18nname_and_i18ntranslate(self): # Let's tell the user this is incredibly silly! self.assertRaises( I18NError, self._compile, '') def test_content_with_plaintext_and_i18nname_and_i18ntranslate(self): # Let's tell the user this is incredibly silly! self.assertRaises( I18NError, self._compile, 'green') def test_translate_static_text_as_dynamic(self): program, macros = self._compile( '
This is text for ' '.' '
') self._check(program, '
THIS IS TEXT FOR BARVALUE.
\n') def test_translate_static_text_as_dynamic_from_bytecode(self): program = [('version', '1.5'), ('mode', 'html'), ('setPosition', (1, 0)), ('beginScope', {'i18n:translate': ''}), ('startTag', ('div', [('i18n:translate', '', 'i18n')])), ('insertTranslation', ('', [('rawtextOffset', ('This is text for ', 17)), ('setPosition', (1, 40)), ('beginScope', {'tal:content': 'bar', 'i18n:name': 'bar_name', 'i18n:translate': ''}), ('i18nVariable', ('bar_name', [('startTag', ('span', [('i18n:translate', '', 'i18n'), ('tal:content', 'bar', 'tal'), ('i18n:name', 'bar_name', 'i18n')])), ('insertTranslation', ('', [('insertText', ('$bar$', []))])), ('rawtextOffset', ('', 7))], None, 0)), ('endScope', ()), ('rawtextOffset', ('.', 1))])), ('endScope', ()), ('rawtextOffset', ('', 6)) ] self._check(program, '
THIS IS TEXT FOR BARVALUE.
\n') def _getCollectingTranslationDomain(self): class CollectingTranslationService(DummyTranslationService): data = [] def translate(self, domain, msgid, mapping=None, context=None, target_language=None, default=None): self.data.append((msgid, mapping)) return DummyTranslationService.translate( self, domain, msgid, mapping, context, target_language, default) xlatsvc = CollectingTranslationService() self.engine.translationService = xlatsvc return xlatsvc def test_for_correct_msgids(self): xlatdmn = self._getCollectingTranslationDomain() result = StringIO() program, macros = self._compile( '
This is text for ' '.
') self.interpreter = TALInterpreter(program, {}, self.engine, stream=result) self.interpreter() msgids = list(xlatdmn.data) msgids.sort() self.assertEqual(2, len(msgids)) self.assertEqual('BaRvAlUe', msgids[0][0]) self.assertEqual('This is text for ${bar_name}.', msgids[1][0]) self.assertEqual({'bar_name': 'BARVALUE'}, msgids[1][1]) self.assertEqual( '
THIS IS TEXT FOR BARVALUE.
\n', result.getvalue()) def test_for_raw_msgids(self): # Test for Issue 314: i18n:translate removes line breaks from # 
...
contents # HTML mode xlatdmn = self._getCollectingTranslationDomain() result = StringIO() program, macros = self._compile( '
This is text\n' ' \tfor\n div.
' '
 This is text\n'
            ' \tfor\n pre.
') self.interpreter = TALInterpreter(program, {}, self.engine, stream=result) self.interpreter() msgids = list(xlatdmn.data) msgids.sort() self.assertEqual(2, len(msgids)) self.assertEqual(' This is text\n \tfor\n pre. ', msgids[0][0]) self.assertEqual('This is text for div.', msgids[1][0]) self.assertEqual( '
THIS IS TEXT FOR DIV.
' '
 THIS IS TEXT\n \tFOR\n PRE.
\n', result.getvalue()) # XML mode xlatdmn = self._getCollectingTranslationDomain() result = StringIO() parser = TALParser() parser.parseString( '\n' '
 This is text\n'
            ' \tfor\n barvalue.
') program, macros = parser.getCode() self.interpreter = TALInterpreter(program, {}, self.engine, stream=result) self.interpreter() msgids = list(xlatdmn.data) msgids.sort() self.assertEqual(1, len(msgids)) self.assertEqual('This is text for barvalue.', msgids[0][0]) self.assertEqual( '\n' '
THIS IS TEXT  FOR BARVALUE.
\n', result.getvalue()) def test_raw_msgids_and_i18ntranslate_i18nname(self): xlatdmn = self._getCollectingTranslationDomain() result = StringIO() program, macros = self._compile( '
This is text\n \tfor\n' '
.
')
        self.interpreter = TALInterpreter(program, {}, self.engine,
                                          stream=result)
        self.interpreter()
        msgids = list(xlatdmn.data)
        msgids.sort()
        self.assertEqual(2, len(msgids))
        self.assertEqual(' \tRaW\n ', msgids[0][0])
        self.assertEqual('This is text for ${raw}.', msgids[1][0])
        self.assertEqual({'raw': '
 \tRAW\n 
'}, msgids[1][1])
        self.assertEqual(
            u'
THIS IS TEXT FOR 
 \tRAW\n 
.
\n',
            result.getvalue())

    def test_for_handling_unicode_vars(self):
        # Make sure that non-ASCII Unicode is substituted correctly.
        # http://collector.zope.org/Zope3-dev/264
        program, macros = self._compile(
            "
"
            "Foo 
")
        self._check(program, u"
FOO \u00C0
\n")

    def test_for_untranslated_messageid_simple(self):
        program, macros = self._compile('')
        self._check(program, "don't translate me\n")
        
    def test_for_untranslated_messageid_i18nname(self):
        program, macros = self._compile(
            '
'
            ''
            '
')
        self._check(program, "
don't translate me
\n")


class I18NErrorsTestCase(TestCaseBase):

    def _check(self, src, msg):
        try:
            self._compile(src)
        except I18NError:
            pass
        else:
            self.fail(msg)

    def test_id_with_replace(self):
        self._check('
',
                    "expected i18n:id with tal:replace to be denied")

    def test_missing_values(self):
        self._check('
',
                    "missing i18n:attributes value not caught")
        self._check('
',
                    "missing i18n:data value not caught")
        self._check('
',
                    "missing i18n:id value not caught")

    def test_id_with_attributes(self):
        self._check('''''',
            "expected attribute being both part of tal:attributes" +
            " and having a msgid in i18n:attributes to be denied")

class OutputPresentationTestCase(TestCaseBase):

    def test_attribute_wrapping(self):
        # To make sure the attribute-wrapping code is invoked, we have to
        # include at least one TAL/METAL attribute to avoid having the start
        # tag optimized into a rawtext instruction.
        INPUT = r"""
        
        """
        EXPECTED = r'''
        
        ''' "\n"
        self.compare(INPUT, EXPECTED)

    def test_unicode_content(self):
        INPUT = """
para
"""
        EXPECTED = u"""
dj-vu
""" "\n"
        self.compare(INPUT, EXPECTED)

    def test_unicode_structure(self):
        INPUT = """
para
"""
        EXPECTED = u"""dj-vu""" "\n"
        self.compare(INPUT, EXPECTED)

    def test_i18n_replace_number(self):
        INPUT = """
        

        para
        
"""
        EXPECTED = u"""
        
FOO 123
""" "\n"
        self.compare(INPUT, EXPECTED)

    def test_entities(self):
        INPUT = ('')
        EXPECTED = ('&a;  
 '
                    '&a &#45 &; &#0a; <>\n')
        self.compare(INPUT, EXPECTED)

    def compare(self, INPUT, EXPECTED):
        program, macros = self._compile(INPUT)
        sio = StringIO()
        interp = TALInterpreter(program, {}, DummyEngine(), sio, wrap=60)
        interp()
        self.assertEqual(sio.getvalue(), EXPECTED)

class InterpolateTestCase(TestCaseBase):

    def test_syntax_ok(self):
        text = "foo ${bar_0MAN} $baz_zz bee"
        mapping = {'bar_0MAN': 'fish', 'baz_zz': 'moo'}
        expected = "foo fish moo bee"
        self.assertEqual(interpolate(text, mapping), expected)

    def test_syntax_bad(self):
        text = "foo $_bar_man} $ ${baz bee"
        mapping = {'_bar_man': 'fish', 'baz': 'moo'}
        expected = text
        self.assertEqual(interpolate(text, mapping), expected)

    def test_missing(self):
        text = "foo ${bar} ${baz}"
        mapping = {'bar': 'fish'}
        expected = "foo fish ${baz}"
        self.assertEqual(interpolate(text, mapping), expected)

    def test_redundant(self):
        text = "foo ${bar}"
        mapping = {'bar': 'fish', 'baz': 'moo'}
        expected = "foo fish"
        self.assertEqual(interpolate(text, mapping), expected)

    def test_numeric(self):
        text = "foo ${bar}"
        mapping = {'bar': 123}
        expected = "foo 123"
        self.assertEqual(interpolate(text, mapping), expected)

    def test_unicode(self):
        text = u"foo ${bar}"
        mapping = {u'bar': u'baz'}
        expected = u"foo baz"
        self.assertEqual(interpolate(text, mapping), expected)

    def test_unicode_mixed_unknown_encoding(self):
        # This test assumes that sys.getdefaultencoding is ascii...
        text = u"foo ${bar}"
        mapping = {u'bar': 'd\xe9j\xe0'}
        expected = u"foo d\\xe9j\\xe0"
        self.assertEqual(interpolate(text, mapping), expected)

def test_suite():
    suite = unittest.makeSuite(I18NErrorsTestCase)
    suite.addTest(unittest.makeSuite(MacroErrorsTestCase))
    suite.addTest(unittest.makeSuite(OutputPresentationTestCase))
    suite.addTest(unittest.makeSuite(I18NCornerTestCase))
    suite.addTest(unittest.makeSuite(InterpolateTestCase))

    return suite

if __name__ == "__main__":
    errs = utils.run_suite(test_suite())
    sys.exit(errs and 1 or 0)
Zope-2.9.4-retire_zpkg/lib/python/TAL/runtest.py0000755000175000017500000001032710337373524021474 0ustar  tseavertseaver#! /usr/bin/env python
##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""
Driver program to run METAL and TAL regression tests.
"""

import sys
import os
from cStringIO import StringIO
import glob
import traceback

if __name__ == "__main__":
    import setpath                      # Local hack to tweak sys.path etc.

import driver
import tests.utils

def showdiff(a, b):
    import ndiff
    cruncher = ndiff.SequenceMatcher(ndiff.IS_LINE_JUNK, a, b)
    for tag, alo, ahi, blo, bhi in cruncher.get_opcodes():
        if tag == "equal":
            continue
        print nicerange(alo, ahi) + tag[0] + nicerange(blo, bhi)
        ndiff.dump('<', a, alo, ahi)
        if a and b:
            print '---'
        ndiff.dump('>', b, blo, bhi)

def nicerange(lo, hi):
    if hi <= lo+1:
        return str(lo+1)
    else:
        return "%d,%d" % (lo+1, hi)

def main():
    opts = []
    args = sys.argv[1:]
    quiet = 0
    unittesting = 0
    if args and args[0] == "-q":
        quiet = 1
        del args[0]
    if args and args[0] == "-Q":
        unittesting = 1
        del args[0]
    while args and args[0].startswith('-'):
        opts.append(args[0])
        del args[0]
    if not args:
        prefix = os.path.join("tests", "input", "test*.")
        if tests.utils.skipxml:
            xmlargs = []
        else:
            xmlargs = glob.glob(prefix + "xml")
            xmlargs.sort()
        htmlargs = glob.glob(prefix + "html")
        htmlargs.sort()
        args = xmlargs + htmlargs
        if not args:
             sys.stderr.write("No tests found -- please supply filenames\n")
             sys.exit(1)
    errors = 0
    for arg in args:
        locopts = []
        if arg.find("metal") >= 0 and "-m" not in opts:
            locopts.append("-m")
        if not unittesting:
            print arg,
            sys.stdout.flush()
        if tests.utils.skipxml and arg.endswith(".xml"):
            print "SKIPPED (XML parser not available)"
            continue
        save = sys.stdout, sys.argv
        try:
            try:
                sys.stdout = stdout = StringIO()
                sys.argv = [""] + opts + locopts + [arg]
                driver.main()
            finally:
                sys.stdout, sys.argv = save
        except SystemExit:
            raise
        except:
            errors = 1
            if quiet:
                print sys.exc_type
                sys.stdout.flush()
            else:
                if unittesting:
                    print
                else:
                    print "Failed:"
                    sys.stdout.flush()
                traceback.print_exc()
            continue
        head, tail = os.path.split(arg)
        outfile = os.path.join(
            head.replace("input", "output"),
            tail)
        try:
            f = open(outfile)
        except IOError:
            expected = None
            print "(missing file %s)" % outfile,
        else:
            expected = f.readlines()
            f.close()
        stdout.seek(0)
        if hasattr(stdout, "readlines"):
            actual = stdout.readlines()
        else:
            actual = readlines(stdout)
        if actual == expected:
            if not unittesting:
                print "OK"
        else:
            if unittesting:
                print
            else:
                print "not OK"
            errors = 1
            if not quiet and expected is not None:
                showdiff(expected, actual)
    if errors:
        sys.exit(1)

def readlines(f):
    L = []
    while 1:
        line = f.readline()
        if not line:
            break
        L.append(line)
    return L

if __name__ == "__main__":
    main()
Zope-2.9.4-retire_zpkg/lib/python/TAL/TranslationContext.py0000644000175000017500000000275710337373524023640 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Translation context object for the TALInterpreter's I18N support.

The translation context provides a container for the information
needed to perform translation of a marked string from a page template.

$Id: TranslationContext.py 40222 2005-11-18 15:46:28Z andreasjung $
"""

DEFAULT_DOMAIN = "default"

class TranslationContext:
    """Information about the I18N settings of a TAL processor."""

    def __init__(self, parent=None, domain=None, target=None, source=None):
        if parent:
            if not domain:
                domain = parent.domain
            if not target:
                target = parent.target
            if not source:
                source = parent.source
        elif domain is None:
            domain = DEFAULT_DOMAIN

        self.parent = parent
        self.domain = domain
        self.target = target
        self.source = source
Zope-2.9.4-retire_zpkg/lib/python/TAL/setpath.py0000644000175000017500000000175710050234363021431 0ustar  tseavertseaver# This software is subject to the provisions of the Zope Public License,
# Version 1.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.

"""
Read a module search path from .path.
"""
import os
import sys

dir = os.path.dirname(__file__)
path = os.path.join(dir, ".path")
try:
    f = open(path)
except IOError:
    raise IOError, "Please edit .path to point to "
else:
    for line in f.readlines():
        line = line.strip()
        if line and line[0] != '#':
            for dir in line.split(os.pathsep):
                dir = os.path.expanduser(os.path.expandvars(dir))
                if dir not in sys.path:
                    sys.path.append(dir)

import ZODB # Must import this first to initialize Persistence properly
Zope-2.9.4-retire_zpkg/lib/python/TAL/HTMLTALParser.py0000644000175000017500000002566610337373524022263 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""
Parse HTML and compile to TALInterpreter intermediate code.
"""

import sys

from TALGenerator import TALGenerator
from HTMLParser import HTMLParser, HTMLParseError
from TALDefs import \
     ZOPE_METAL_NS, ZOPE_TAL_NS, ZOPE_I18N_NS, METALError, TALError, I18NError

BOOLEAN_HTML_ATTRS = [
    # List of Boolean attributes in HTML that may be given in
    # minimized form (e.g.  rather than )
    # From http://www.w3.org/TR/xhtml1/#guidelines (C.10)
    "compact", "nowrap", "ismap", "declare", "noshade", "checked",
    "disabled", "readonly", "multiple", "selected", "noresize",
    "defer"
    ]

EMPTY_HTML_TAGS = [
    # List of HTML tags with an empty content model; these are
    # rendered in minimized form, e.g. .
    # From http://www.w3.org/TR/xhtml1/#dtds
    "base", "meta", "link", "hr", "br", "param", "img", "area",
    "input", "col", "basefont", "isindex", "frame",
    ]

PARA_LEVEL_HTML_TAGS = [
    # List of HTML elements that close open paragraph-level elements
    # and are themselves paragraph-level.
    "h1", "h2", "h3", "h4", "h5", "h6", "p",
    ]

BLOCK_CLOSING_TAG_MAP = {
    "tr": ("tr", "td", "th"),
    "td": ("td", "th"),
    "th": ("td", "th"),
    "li": ("li",),
    "dd": ("dd", "dt"),
    "dt": ("dd", "dt"),
    }

BLOCK_LEVEL_HTML_TAGS = [
    # List of HTML tags that denote larger sections than paragraphs.
    "blockquote", "table", "tr", "th", "td", "thead", "tfoot", "tbody",
    "noframe", "ul", "ol", "li", "dl", "dt", "dd", "div",
    ]

TIGHTEN_IMPLICIT_CLOSE_TAGS = (PARA_LEVEL_HTML_TAGS
                               + BLOCK_CLOSING_TAG_MAP.keys())


class NestingError(HTMLParseError):
    """Exception raised when elements aren't properly nested."""

    def __init__(self, tagstack, endtag, position=(None, None)):
        self.endtag = endtag
        if tagstack:
            if len(tagstack) == 1:
                msg = ('Open tag <%s> does not match close tag '
                       % (tagstack[0], endtag))
            else:
                msg = ('Open tags <%s> do not match close tag '
                       % ('>, <'.join(tagstack), endtag))
        else:
            msg = 'No tags are open to match ' % endtag
        HTMLParseError.__init__(self, msg, position)

class EmptyTagError(NestingError):
    """Exception raised when empty elements have an end tag."""

    def __init__(self, tag, position=(None, None)):
        self.tag = tag
        msg = 'Close tag  should be removed' % tag
        HTMLParseError.__init__(self, msg, position)

class OpenTagError(NestingError):
    """Exception raised when a tag is not allowed in another tag."""

    def __init__(self, tagstack, tag, position=(None, None)):
        self.tag = tag
        msg = 'Tag <%s> is not allowed in <%s>' % (tag, tagstack[-1])
        HTMLParseError.__init__(self, msg, position)

class HTMLTALParser(HTMLParser):

    # External API

    def __init__(self, gen=None):
        HTMLParser.__init__(self)
        if gen is None:
            gen = TALGenerator(xml=0)
        self.gen = gen
        self.tagstack = []
        self.nsstack = []
        self.nsdict = {'tal': ZOPE_TAL_NS,
                       'metal': ZOPE_METAL_NS,
                       'i18n': ZOPE_I18N_NS,
                       }

    def parseFile(self, file):
        f = open(file)
        data = f.read()
        f.close()
        try:
            self.parseString(data)
        except TALError, e:
            e.setFile(file)
            raise

    def parseString(self, data):
        self.feed(data)
        self.close()
        while self.tagstack:
            self.implied_endtag(self.tagstack[-1], 2)
        assert self.nsstack == [], self.nsstack

    def getCode(self):
        return self.gen.getCode()

    def getWarnings(self):
        return ()

    # Overriding HTMLParser methods

    def handle_starttag(self, tag, attrs):
        self.close_para_tags(tag)
        self.scan_xmlns(attrs)
        tag, attrlist, taldict, metaldict, i18ndict \
             = self.process_ns(tag, attrs)
        if tag in EMPTY_HTML_TAGS and taldict.get("content"):
            raise TALError(
                "empty HTML tags cannot use tal:content: %s" % `tag`,
                self.getpos())
        self.tagstack.append(tag)
        self.gen.emitStartElement(tag, attrlist, taldict, metaldict, i18ndict,
                                  self.getpos())
        if tag in EMPTY_HTML_TAGS:
            self.implied_endtag(tag, -1)

    def handle_startendtag(self, tag, attrs):
        self.close_para_tags(tag)
        self.scan_xmlns(attrs)
        tag, attrlist, taldict, metaldict, i18ndict \
             = self.process_ns(tag, attrs)
        if taldict.get("content"):
            if tag in EMPTY_HTML_TAGS:
                raise TALError(
                    "empty HTML tags cannot use tal:content: %s" % `tag`,
                    self.getpos())
            self.gen.emitStartElement(tag, attrlist, taldict, metaldict,
                                      i18ndict, self.getpos())
            self.gen.emitEndElement(tag, implied=-1)
        else:
            self.gen.emitStartElement(tag, attrlist, taldict, metaldict,
                                      i18ndict, self.getpos(), isend=1)
        self.pop_xmlns()

    def handle_endtag(self, tag):
        if tag in EMPTY_HTML_TAGS:
            #  etc. in the source is an error
            raise EmptyTagError(tag, self.getpos())
        self.close_enclosed_tags(tag)
        self.gen.emitEndElement(tag)
        self.pop_xmlns()
        self.tagstack.pop()

    def close_para_tags(self, tag):
        if tag in EMPTY_HTML_TAGS:
            return
        close_to = -1
        if BLOCK_CLOSING_TAG_MAP.has_key(tag):
            blocks_to_close = BLOCK_CLOSING_TAG_MAP[tag]
            for i in range(len(self.tagstack)):
                t = self.tagstack[i]
                if t in blocks_to_close:
                    if close_to == -1:
                        close_to = i
                elif t in BLOCK_LEVEL_HTML_TAGS:
                    close_to = -1
        elif tag in PARA_LEVEL_HTML_TAGS + BLOCK_LEVEL_HTML_TAGS:
            i = len(self.tagstack) - 1
            while i >= 0:
                closetag = self.tagstack[i]
                if closetag in BLOCK_LEVEL_HTML_TAGS:
                    break
                if closetag in PARA_LEVEL_HTML_TAGS:
                    if closetag != "p":
                        raise OpenTagError(self.tagstack, tag, self.getpos())
                    close_to = i
                i = i - 1
        if close_to >= 0:
            while len(self.tagstack) > close_to:
                self.implied_endtag(self.tagstack[-1], 1)

    def close_enclosed_tags(self, tag):
        if tag not in self.tagstack:
            raise NestingError(self.tagstack, tag, self.getpos())
        while tag != self.tagstack[-1]:
            self.implied_endtag(self.tagstack[-1], 1)
        assert self.tagstack[-1] == tag

    def implied_endtag(self, tag, implied):
        assert tag == self.tagstack[-1]
        assert implied in (-1, 1, 2)
        isend = (implied < 0)
        if tag in TIGHTEN_IMPLICIT_CLOSE_TAGS:
            # Pick out trailing whitespace from the program, and
            # insert the close tag before the whitespace.
            white = self.gen.unEmitWhitespace()
        else:
            white = None
        self.gen.emitEndElement(tag, isend=isend, implied=implied)
        if white:
            self.gen.emitRawText(white)
        self.tagstack.pop()
        self.pop_xmlns()

    def handle_charref(self, name):
        self.gen.emitRawText("&#%s;" % name)

    def handle_entityref(self, name):
        self.gen.emitRawText("&%s;" % name)

    def handle_data(self, data):
        self.gen.emitRawText(data)

    def handle_comment(self, data):
        self.gen.emitRawText("" % data)

    def handle_decl(self, data):
        self.gen.emitRawText("" % data)

    def handle_pi(self, data):
        self.gen.emitRawText("" % data)

    # Internal thingies

    def scan_xmlns(self, attrs):
        nsnew = {}
        for key, value in attrs:
            if key.startswith("xmlns:"):
                nsnew[key[6:]] = value
        if nsnew:
            self.nsstack.append(self.nsdict)
            self.nsdict = self.nsdict.copy()
            self.nsdict.update(nsnew)
        else:
            self.nsstack.append(self.nsdict)

    def pop_xmlns(self):
        self.nsdict = self.nsstack.pop()

    def fixname(self, name):
        if ':' in name:
            prefix, suffix = name.split(':', 1)
            if prefix == 'xmlns':
                nsuri = self.nsdict.get(suffix)
                if nsuri in (ZOPE_TAL_NS, ZOPE_METAL_NS, ZOPE_I18N_NS):
                    return name, name, prefix
            else:
                nsuri = self.nsdict.get(prefix)
                if nsuri == ZOPE_TAL_NS:
                    return name, suffix, 'tal'
                elif nsuri == ZOPE_METAL_NS:
                    return name, suffix,  'metal'
                elif nsuri == ZOPE_I18N_NS:
                    return name, suffix, 'i18n'
        return name, name, 0

    def process_ns(self, name, attrs):
        attrlist = []
        taldict = {}
        metaldict = {}
        i18ndict = {}
        name, namebase, namens = self.fixname(name)
        for item in attrs:
            key, value = item
            key, keybase, keyns = self.fixname(key)
            ns = keyns or namens # default to tag namespace
            if ns and ns != 'unknown':
                item = (key, value, ns)
            if ns == 'tal':
                if taldict.has_key(keybase):
                    raise TALError("duplicate TAL attribute " +
                                   `keybase`, self.getpos())
                taldict[keybase] = value
            elif ns == 'metal':
                if metaldict.has_key(keybase):
                    raise METALError("duplicate METAL attribute " +
                                     `keybase`, self.getpos())
                metaldict[keybase] = value
            elif ns == 'i18n':
                if i18ndict.has_key(keybase):
                    raise I18NError("duplicate i18n attribute " +
                                    `keybase`, self.getpos())
                i18ndict[keybase] = value
            attrlist.append(item)
        if namens in ('metal', 'tal'):
            taldict['tal tag'] = namens
        return name, attrlist, taldict, metaldict, i18ndict
Zope-2.9.4-retire_zpkg/lib/python/TAL/XMLParser.py0000644000175000017500000000530010337373524021575 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""
Generic expat-based XML parser base class.
"""

import xml.parsers.expat

import zLOG


XMLParseError = xml.parsers.expat.ExpatError


class XMLParser:

    ordered_attributes = 0

    handler_names = [
        "StartElementHandler",
        "EndElementHandler",
        "ProcessingInstructionHandler",
        "CharacterDataHandler",
        "UnparsedEntityDeclHandler",
        "NotationDeclHandler",
        "StartNamespaceDeclHandler",
        "EndNamespaceDeclHandler",
        "CommentHandler",
        "StartCdataSectionHandler",
        "EndCdataSectionHandler",
        "DefaultHandler",
        "DefaultHandlerExpand",
        "NotStandaloneHandler",
        "ExternalEntityRefHandler",
        "XmlDeclHandler",
        "StartDoctypeDeclHandler",
        "EndDoctypeDeclHandler",
        "ElementDeclHandler",
        "AttlistDeclHandler"
        ]

    def __init__(self, encoding=None):
        self.parser = p = self.createParser()
        if self.ordered_attributes:
            try:
                self.parser.ordered_attributes = self.ordered_attributes
            except AttributeError:
                zLOG.LOG("TAL.XMLParser", zLOG.INFO, 
                         "Can't set ordered_attributes")
                self.ordered_attributes = 0
        for name in self.handler_names:
            method = getattr(self, name, None)
            if method is not None:
                try:
                    setattr(p, name, method)
                except AttributeError:
                    zLOG.LOG("TAL.XMLParser", zLOG.PROBLEM,
                             "Can't set expat handler %s" % name)

    def createParser(self, encoding=None):
        return xml.parsers.expat.ParserCreate(encoding, ' ')

    def parseFile(self, filename):
        self.parseStream(open(filename))

    def parseString(self, s):
        self.parser.Parse(s, 1)

    def parseURL(self, url):
        import urllib
        self.parseStream(urllib.urlopen(url))

    def parseStream(self, stream):
        self.parser.ParseFile(stream)

    def parseFragment(self, s, end=0):
        self.parser.Parse(s, end)
Zope-2.9.4-retire_zpkg/lib/python/TAL/timer.py0000755000175000017500000000330010337373524021101 0ustar  tseavertseaver#! /usr/bin/env python
##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""
Helper program to time compilation and interpretation
"""

import sys
import time
import getopt
from cPickle import dumps, loads
from cStringIO import StringIO

from driver import FILE, compilefile, interpretit

def main():
    count = 10
    try:
        opts, args = getopt.getopt(sys.argv[1:], "n:")
    except getopt.error, msg:
        print msg
        sys.exit(2)
    for o, a in opts:
        if o == "-n":
            count = int(a)
    if not args:
        args = [FILE]
    for file in args:
        print file
        dummyfile = StringIO()
        it = timefunc(count, compilefile, file)
        timefunc(count, interpretit, it, None, dummyfile)

def timefunc(count, func, *args):
    sys.stderr.write("%-14s: " % func.__name__)
    sys.stderr.flush()
    t0 = time.clock()
    for i in range(count):
        result = func(*args)
    t1 = time.clock()
    sys.stderr.write("%6.3f secs for %d calls, i.e. %4.0f msecs per call\n"
                     % ((t1-t0), count, 1000*(t1-t0)/count))
    return result

if __name__ == "__main__":
    main()
Zope-2.9.4-retire_zpkg/lib/python/TAL/ITALES.py0000644000175000017500000001121410050234363020727 0ustar  tseavertseaver"""Interface that a TALES engine provides to the METAL/TAL implementation."""

try:
    from Interface import Interface
    from Interface.Attribute import Attribute
except:
    # Before 2.7
    class Interface: pass
    def Attribute(*args): pass


class ITALESCompiler(Interface):
    """Compile-time interface provided by a TALES implementation.

    The TAL compiler needs an instance of this interface to support
    compilation of TALES expressions embedded in documents containing
    TAL and METAL constructs.
    """

    def getCompilerError():
        """Return the exception class raised for compilation errors.
        """

    def compile(expression):
        """Return a compiled form of 'expression' for later evaluation.

        'expression' is the source text of the expression.

        The return value may be passed to the various evaluate*()
        methods of the ITALESEngine interface.  No compatibility is
        required for the values of the compiled expression between
        different ITALESEngine implementations.
        """


class ITALESEngine(Interface):
    """Render-time interface provided by a TALES implementation.

    The TAL interpreter uses this interface to TALES to support
    evaluation of the compiled expressions returned by
    ITALESCompiler.compile().
    """

    def getCompiler():
        """Return an object that supports ITALESCompiler."""

    def getDefault():
        """Return the value of the 'default' TALES expression.

        Checking a value for a match with 'default' should be done
        using the 'is' operator in Python.
        """

    def setPosition((lineno, offset)):
        """Inform the engine of the current position in the source file.

        This is used to allow the evaluation engine to report
        execution errors so that site developers can more easily
        locate the offending expression.
        """

    def setSourceFile(filename):
        """Inform the engine of the name of the current source file.

        This is used to allow the evaluation engine to report
        execution errors so that site developers can more easily
        locate the offending expression.
        """

    def beginScope():
        """Push a new scope onto the stack of open scopes.
        """

    def endScope():
        """Pop one scope from the stack of open scopes.
        """

    def evaluate(compiled_expression):
        """Evaluate an arbitrary expression.

        No constraints are imposed on the return value.
        """

    def evaluateBoolean(compiled_expression):
        """Evaluate an expression that must return a Boolean value.
        """

    def evaluateMacro(compiled_expression):
        """Evaluate an expression that must return a macro program.
        """

    def evaluateStructure(compiled_expression):
        """Evaluate an expression that must return a structured
        document fragment.

        The result of evaluating 'compiled_expression' must be a
        string containing a parsable HTML or XML fragment.  Any TAL
        markup cnotained in the result string will be interpreted.
        """

    def evaluateText(compiled_expression):
        """Evaluate an expression that must return text.

        The returned text should be suitable for direct inclusion in
        the output: any HTML or XML escaping or quoting is the
        responsibility of the expression itself.
        """

    def evaluateValue(compiled_expression):
        """Evaluate an arbitrary expression.

        No constraints are imposed on the return value.
        """

    def createErrorInfo(exception, (lineno, offset)):
        """Returns an ITALESErrorInfo object.

        The returned object is used to provide information about the
        error condition for the on-error handler.
        """

    def setGlobal(name, value):
        """Set a global variable.

        The variable will be named 'name' and have the value 'value'.
        """

    def setLocal(name, value):
        """Set a local variable in the current scope.

        The variable will be named 'name' and have the value 'value'.
        """

    def setRepeat(name, compiled_expression):
        """
        """

    def translate(domain, msgid, mapping, default=None):
        """
        See ITranslationService.translate()
        """


class ITALESErrorInfo(Interface):

    type = Attribute("type",
                     "The exception class.")

    value = Attribute("value",
                      "The exception instance.")

    lineno = Attribute("lineno",
                       "The line number the error occurred on in the source.")

    offset = Attribute("offset",
                       "The character offset at which the error occurred.")
Zope-2.9.4-retire_zpkg/lib/python/TAL/DummyEngine.py0000644000175000017500000002025210337373524022204 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""
Dummy TALES engine so that I can test out the TAL implementation.
"""

import re
import sys

from TALDefs import NAME_RE, TALESError, ErrorInfo
from ITALES import ITALESCompiler, ITALESEngine
from DocumentTemplate.DT_Util import ustr

class _Default:
    pass
Default = _Default()

name_match = re.compile(r"(?s)(%s):(.*)\Z" % NAME_RE).match

class CompilerError(Exception):
    pass

class DummyEngine:

    position = None
    source_file = None

    __implements__ = ITALESCompiler, ITALESEngine

    def __init__(self, macros=None):
        if macros is None:
            macros = {}
        self.macros = macros
        dict = {'nothing': None, 'default': Default}
        self.locals = self.globals = dict
        self.stack = [dict]
        self.translationService = DummyTranslationService()

    def getCompilerError(self):
        return CompilerError

    def getCompiler(self):
        return self

    def setSourceFile(self, source_file):
        self.source_file = source_file

    def setPosition(self, position):
        self.position = position

    def compile(self, expr):
        return "$%s$" % expr

    def uncompile(self, expression):
        assert (expression.startswith("$") and expression.endswith("$"),
            expression)
        return expression[1:-1]

    def beginScope(self):
        self.stack.append(self.locals)

    def endScope(self):
        assert len(self.stack) > 1, "more endScope() than beginScope() calls"
        self.locals = self.stack.pop()

    def setLocal(self, name, value):
        if self.locals is self.stack[-1]:
            # Unmerge this scope's locals from previous scope of first set
            self.locals = self.locals.copy()
        self.locals[name] = value

    def setGlobal(self, name, value):
        self.globals[name] = value

    def evaluate(self, expression):
        assert (expression.startswith("$") and expression.endswith("$"),
            expression)
        expression = expression[1:-1]
        m = name_match(expression)
        if m:
            type, expr = m.group(1, 2)
        else:
            type = "path"
            expr = expression
        if type in ("string", "str"):
            return expr
        if type in ("path", "var", "global", "local"):
            return self.evaluatePathOrVar(expr)
        if type == "not":
            return not self.evaluate(expr)
        if type == "exists":
            return self.locals.has_key(expr) or self.globals.has_key(expr)
        if type == "python":
            try:
                return eval(expr, self.globals, self.locals)
            except:
                raise TALESError("evaluation error in %s" % `expr`)
        if type == "position":
            # Insert the current source file name, line number,
            # and column offset.
            if self.position:
                lineno, offset = self.position
            else:
                lineno, offset = None, None
            return '%s (%s,%s)' % (self.source_file, lineno, offset)
        raise TALESError("unrecognized expression: " + `expression`)

    def evaluatePathOrVar(self, expr):
        expr = expr.strip()
        if self.locals.has_key(expr):
            return self.locals[expr]
        elif self.globals.has_key(expr):
            return self.globals[expr]
        else:
            raise TALESError("unknown variable: %s" % `expr`)

    def evaluateValue(self, expr):
        return self.evaluate(expr)

    def evaluateBoolean(self, expr):
        return self.evaluate(expr)

    def evaluateText(self, expr):
        text = self.evaluate(expr)
        if text is not None and text is not Default:
            text = ustr(text)
        return text

    def evaluateStructure(self, expr):
        # XXX Should return None or a DOM tree
        return self.evaluate(expr)

    def evaluateSequence(self, expr):
        # XXX Should return a sequence
        return self.evaluate(expr)

    def evaluateMacro(self, macroName):
        assert (macroName.startswith("$") and macroName.endswith("$"),
            macroName)
        macroName = macroName[1:-1]
        file, localName = self.findMacroFile(macroName)
        if not file:
            # Local macro
            macro = self.macros[localName]
        else:
            # External macro
            import driver
            program, macros = driver.compilefile(file)
            macro = macros.get(localName)
            if not macro:
                raise TALESError("macro %s not found in file %s" %
                                 (localName, file))
        return macro

    def findMacroDocument(self, macroName):
        file, localName = self.findMacroFile(macroName)
        if not file:
            return file, localName
        import driver
        doc = driver.parsefile(file)
        return doc, localName

    def findMacroFile(self, macroName):
        if not macroName:
            raise TALESError("empty macro name")
        i = macroName.rfind('/')
        if i < 0:
            # No slash -- must be a locally defined macro
            return None, macroName
        else:
            # Up to last slash is the filename
            fileName = macroName[:i]
            localName = macroName[i+1:]
            return fileName, localName

    def setRepeat(self, name, expr):
        seq = self.evaluateSequence(expr)
        return Iterator(name, seq, self)

    def createErrorInfo(self, err, position):
        return ErrorInfo(err, position)

    def getDefault(self):
        return Default

    def translate(self, domain, msgid, mapping, default=None):
        return self.translationService.translate(domain, msgid, mapping,
                                                 default=default)


class Iterator:

    # This is not an implementation of a Python iterator.  The next()
    # method returns true or false to indicate whether another item is
    # available; if there is another item, the iterator instance calls
    # setLocal() on the evaluation engine passed to the constructor.

    def __init__(self, name, seq, engine):
        self.name = name
        self.seq = seq
        self.engine = engine
        self.nextIndex = 0

    def next(self):
        i = self.nextIndex
        try:
            item = self.seq[i]
        except IndexError:
            return 0
        self.nextIndex = i+1
        self.engine.setLocal(self.name, item)
        return 1

class DummyDomain:

    def translate(self, msgid, mapping=None, context=None,
                  target_language=None, default=None):
        # This is a fake translation service which simply uppercases non
        # ${name} placeholder text in the message id.
        #
        # First, transform a string with ${name} placeholders into a list of
        # substrings.  Then upcase everything but the placeholders, then glue
        # things back together.

        # simulate an unknown msgid by returning None
        text = msgid
        if msgid == "don't translate me":
            if default is not None:
                text = default
        else:
            text = msgid.upper()

        def repl(m, mapping=mapping):
            return ustr(mapping[m.group(m.lastindex).lower()])
        cre = re.compile(r'\$(?:(%s)|\{(%s)\})' % (NAME_RE, NAME_RE))
        return cre.sub(repl, text)

class DummyTranslationService:

    def translate(self, domain, msgid, mapping=None, context=None,
                  target_language=None, default=None):
        return self.getDomain(domain).translate(msgid, mapping, context,
                                                target_language,
                                                default=default)

    def getDomain(self, domain):
        return DummyDomain()
Zope-2.9.4-retire_zpkg/lib/python/TAL/TALDefs.py0000644000175000017500000001237110337373524021210 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""
Common definitions used by TAL and METAL compilation an transformation.
"""

from types import ListType, TupleType

from ITALES import ITALESErrorInfo

TAL_VERSION = "1.5"

XML_NS = "http://www.w3.org/XML/1998/namespace" # URI for XML namespace
XMLNS_NS = "http://www.w3.org/2000/xmlns/" # URI for XML NS declarations

ZOPE_TAL_NS = "http://xml.zope.org/namespaces/tal"
ZOPE_METAL_NS = "http://xml.zope.org/namespaces/metal"
ZOPE_I18N_NS = "http://xml.zope.org/namespaces/i18n"

# This RE must exactly match the expression of the same name in the
# zope.i18n.simpletranslationservice module:
NAME_RE = "[a-zA-Z_][-a-zA-Z0-9_]*"

KNOWN_METAL_ATTRIBUTES = [
    "define-macro",
    "use-macro",
    "define-slot",
    "fill-slot",
    "slot",
    ]

KNOWN_TAL_ATTRIBUTES = [
    "define",
    "condition",
    "content",
    "replace",
    "repeat",
    "attributes",
    "on-error",
    "omit-tag",
    "tal tag",
    ]

KNOWN_I18N_ATTRIBUTES = [
    "translate",
    "domain",
    "target",
    "source",
    "attributes",
    "data",
    "name",
    ]

class TALError(Exception):

    def __init__(self, msg, position=(None, None)):
        assert msg != ""
        self.msg = msg
        self.lineno = position[0]
        self.offset = position[1]
        self.filename = None

    def setFile(self, filename):
        self.filename = filename

    def __str__(self):
        result = self.msg
        if self.lineno is not None:
            result = result + ", at line %d" % self.lineno
        if self.offset is not None:
            result = result + ", column %d" % (self.offset + 1)
        if self.filename is not None:
            result = result + ', in file %s' % self.filename
        return result

class METALError(TALError):
    pass

class TALESError(TALError):
    pass

class I18NError(TALError):
    pass


class ErrorInfo:

    __implements__ = ITALESErrorInfo

    def __init__(self, err, position=(None, None)):
        if isinstance(err, Exception):
            self.type = err.__class__
            self.value = err
        else:
            self.type = err
            self.value = None
        self.lineno = position[0]
        self.offset = position[1]



import re
_attr_re = re.compile(r"\s*([^\s]+)\s+([^\s].*)\Z", re.S)
_subst_re = re.compile(r"\s*(?:(text|structure)\s+)?(.*)\Z", re.S)
del re

def parseAttributeReplacements(arg, xml):
    dict = {}
    for part in splitParts(arg):
        m = _attr_re.match(part)
        if not m:
            raise TALError("Bad syntax in attributes: " + `part`)
        name, expr = m.group(1, 2)
        if not xml:
            name = name.lower()
        if dict.has_key(name):
            raise TALError("Duplicate attribute name in attributes: " + `part`)
        dict[name] = expr
    return dict

def parseSubstitution(arg, position=(None, None)):
    m = _subst_re.match(arg)
    if not m:
        raise TALError("Bad syntax in substitution text: " + `arg`, position)
    key, expr = m.group(1, 2)
    if not key:
        key = "text"
    return key, expr

def splitParts(arg):
    # Break in pieces at undoubled semicolons and
    # change double semicolons to singles:
    arg = arg.replace(";;", "\0")
    parts = arg.split(';')
    parts = [p.replace("\0", ";") for p in parts]
    if len(parts) > 1 and not parts[-1].strip():
        del parts[-1] # It ended in a semicolon
    return parts

def isCurrentVersion(program):
    version = getProgramVersion(program)
    return version == TAL_VERSION

def getProgramMode(program):
    version = getProgramVersion(program)
    if (version == TAL_VERSION and isinstance(program[1], TupleType) and
        len(program[1]) == 2):
        opcode, mode = program[1]
        if opcode == "mode":
            return mode
    return None

def getProgramVersion(program):
    if (len(program) >= 2 and
        isinstance(program[0], TupleType) and len(program[0]) == 2):
        opcode, version = program[0]
        if opcode == "version":
            return version
    return None

import re
_ent1_re = re.compile('&(?![A-Z#])', re.I)
_entch_re = re.compile('&([A-Z][A-Z0-9]*)(?![A-Z0-9;])', re.I)
_entn1_re = re.compile('&#(?![0-9X])', re.I)
_entnx_re = re.compile('&(#X[A-F0-9]*)(?![A-F0-9;])', re.I)
_entnd_re = re.compile('&(#[0-9][0-9]*)(?![0-9;])')
del re

def attrEscape(s):
    """Replace special characters '&<>' by character entities,
    except when '&' already begins a syntactically valid entity."""
    s = _ent1_re.sub('&', s)
    s = _entch_re.sub(r'&\1', s)
    s = _entn1_re.sub('&#', s)
    s = _entnx_re.sub(r'&\1', s)
    s = _entnd_re.sub(r'&\1', s)
    s = s.replace('<', '<')
    s = s.replace('>', '>')
    s = s.replace('"', '"')
    return s
Zope-2.9.4-retire_zpkg/lib/python/TAL/talgettext.py0000755000175000017500000002252010337373524022153 0ustar  tseavertseaver


#!/usr/bin/env python
##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################

"""Program to extract internationalization markup from Page Templates.

Once you have marked up a Page Template file with i18n: namespace tags, use
this program to extract GNU gettext .po file entries.

Usage: talgettext.py [options] files
Options:
    -h / --help
        Print this message and exit.
    -o / --output 
        Output the translation .po file to .
    -u / --update 
        Update the existing translation  with any new translation strings
        found.
"""

import sys
import time
import getopt
import traceback

from TAL.HTMLTALParser import HTMLTALParser
from TAL.TALInterpreter import TALInterpreter
from TAL.DummyEngine import DummyEngine
from ITALES import ITALESEngine
from TAL.TALDefs import TALESError

__version__ = '$Revision: 1.1.2.1 $'

pot_header = '''\
# SOME DESCRIPTIVE TITLE.
# Copyright (C) YEAR ORGANIZATION
# FIRST AUTHOR , YEAR.
#
msgid ""
msgstr ""
"Project-Id-Version: PACKAGE VERSION\\n"
"POT-Creation-Date: %(time)s\\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\\n"
"Last-Translator: FULL NAME \\n"
"Language-Team: LANGUAGE \\n"
"MIME-Version: 1.0\\n"
"Content-Type: text/plain; charset=CHARSET\\n"
"Content-Transfer-Encoding: ENCODING\\n"
"Generated-By: talgettext.py %(version)s\\n"
'''

NLSTR = '"\n"'

try:
    True
except NameError:
    True=1
    False=0

def usage(code, msg=''):
    # Python 2.1 required
    print >> sys.stderr, __doc__
    if msg:
        print >> sys.stderr, msg
    sys.exit(code)


class POTALInterpreter(TALInterpreter):
    def translate(self, msgid, default, i18ndict=None, obj=None):
        # XXX is this right?
        if i18ndict is None:
            i18ndict = {}
        if obj:
            i18ndict.update(obj)
        # XXX Mmmh, it seems that sometimes the msgid is None; is that really
        # possible?
        if msgid is None:
            return None
        # XXX We need to pass in one of context or target_language
        return self.engine.translate(msgid, self.i18nContext.domain, i18ndict,
                                     position=self.position, default=default)


class POEngine(DummyEngine):
    __implements__ = ITALESEngine

    def __init__(self, macros=None):
        self.catalog = {}
        DummyEngine.__init__(self, macros)

    def evaluate(*args):
        return '' # who cares

    def evaluatePathOrVar(*args):
        return '' # who cares

    def evaluateSequence(self, expr):
        return (0,) # dummy

    def evaluateBoolean(self, expr):
        return True # dummy

    def translate(self, msgid, domain=None, mapping=None, default=None,
                  # XXX position is not part of the ITALESEngine
                  #     interface
                  position=None):

        if domain not in self.catalog:
            self.catalog[domain] = {}
        domain = self.catalog[domain]

        # ---------------------------------------------
        # only non-empty msgids are added to dictionary
        # (changed by heinrichbernd - 2004/09/07)
        # ---------------------------------------------
        if msgid:
            if msgid not in domain:
                domain[msgid] = []
            domain[msgid].append((self.file, position))
        return 'x'


class UpdatePOEngine(POEngine):
    """A slightly-less braindead POEngine which supports loading an existing
    .po file first."""

    def __init__ (self, macros=None, filename=None):
        POEngine.__init__(self, macros)

        self._filename = filename
        self._loadFile()
        self.base = self.catalog
        self.catalog = {}

    def __add(self, id, s, fuzzy):
        "Add a non-fuzzy translation to the dictionary."
        if not fuzzy and str:
            # check for multi-line values and munge them appropriately
            if '\n' in s:
                lines = s.rstrip().split('\n')
                s = NLSTR.join(lines)
            self.catalog[id] = s

    def _loadFile(self):
        # shamelessly cribbed from Python's Tools/i18n/msgfmt.py
        # 25-Mar-2003 Nathan R. Yergler (nathan@zope.org)
        # 14-Apr-2003 Hacked by Barry Warsaw (barry@zope.com)

        ID = 1
        STR = 2

        try:
            lines = open(self._filename).readlines()
        except IOError, msg:
            print >> sys.stderr, msg
            sys.exit(1)

        section = None
        fuzzy = False

        # Parse the catalog
        lno = 0
        for l in lines:
            lno += True
            # If we get a comment line after a msgstr, this is a new entry
            if l[0] == '#' and section == STR:
                self.__add(msgid, msgstr, fuzzy)
                section = None
                fuzzy = False
            # Record a fuzzy mark
            if l[:2] == '#,' and l.find('fuzzy'):
                fuzzy = True
            # Skip comments
            if l[0] == '#':
                continue
            # Now we are in a msgid section, output previous section
            if l.startswith('msgid'):
                if section == STR:
                    self.__add(msgid, msgstr, fuzzy)
                section = ID
                l = l[5:]
                msgid = msgstr = ''
            # Now we are in a msgstr section
            elif l.startswith('msgstr'):
                section = STR
                l = l[6:]
            # Skip empty lines
            if not l.strip():
                continue
            # XXX: Does this always follow Python escape semantics?
            l = eval(l)
            if section == ID:
                msgid += l
            elif section == STR:
                msgstr += '%s\n' % l
            else:
                print >> sys.stderr, 'Syntax error on %s:%d' % (infile, lno), \
                      'before:'
                print >> sys.stderr, l
                sys.exit(1)
        # Add last entry
        if section == STR:
            self.__add(msgid, msgstr, fuzzy)

    def evaluate(self, expression):
        try:
            return POEngine.evaluate(self, expression)
        except TALESError:
            pass

    def evaluatePathOrVar(self, expr):
        return 'who cares'

    def translate(self, msgid, domain=None, mapping=None, default=None,
                  position=None):
        if msgid not in self.base:
            POEngine.translate(self, msgid, domain, mapping, default, position)
        return 'x'


def main():
    try:
        opts, args = getopt.getopt(
            sys.argv[1:],
            'ho:u:',
            ['help', 'output=', 'update='])
    except getopt.error, msg:
        usage(1, msg)

    outfile = None
    engine = None
    update_mode = False
    for opt, arg in opts:
        if opt in ('-h', '--help'):
            usage(0)
        elif opt in ('-o', '--output'):
            outfile = arg
        elif opt in ('-u', '--update'):
            update_mode = True
            if outfile is None:
                outfile = arg
            engine = UpdatePOEngine(filename=arg)

    if not args:
        print 'nothing to do'
        return

    # We don't care about the rendered output of the .pt file
    class Devnull:
        def write(self, s):
            pass

    # check if we've already instantiated an engine;
    # if not, use the stupidest one available
    if not engine:
        engine = POEngine()

    # process each file specified
    for filename in args:
        try:
            engine.file = filename
            p = HTMLTALParser()
            p.parseFile(filename)
            program, macros = p.getCode()
            POTALInterpreter(program, macros, engine, stream=Devnull(),
                             metal=False)()
        except: # Hee hee, I love bare excepts!
            print 'There was an error processing', filename
            traceback.print_exc()

    # Now output the keys in the engine.  Write them to a file if --output or
    # --update was specified; otherwise use standard out.
    if (outfile is None):
        outfile = sys.stdout
    else:
        outfile = file(outfile, update_mode and "a" or "w")
    catalog = {}
    for domain in engine.catalog.keys():
        catalog.update(engine.catalog[domain])

    messages = catalog.copy()
    try:
        messages.update(engine.base)
    except AttributeError:
        pass
    if '' not in messages:
        print >> outfile, pot_header % {'time': time.ctime(),
                                        'version': __version__}

    msgids = catalog.keys()
    # XXX: You should not sort by msgid, but by filename and position. (SR)
    msgids.sort()
    for msgid in msgids:
        positions = catalog[msgid]
        for filename, position in positions:
            outfile.write('#: %s:%s\n' % (filename, position[0]))

        outfile.write('msgid "%s"\n' % msgid)
        outfile.write('msgstr ""\n')
        outfile.write('\n')


if __name__ == '__main__':
    main()
Zope-2.9.4-retire_zpkg/lib/python/TAL/README.txt0000644000175000017500000000673610050234363021107 0ustar  tseavertseaverTAL - Template Attribute Language
---------------------------------

This is an implementation of TAL, the Zope Template Attribute
Language.  For TAL, see the Zope Presentation Templates ZWiki:

    http://dev.zope.org/Wikis/DevSite/Projects/ZPT/FrontPage

It is not a Zope product nor is it designed exclusively to run inside
of Zope, but if you have a Zope checkout that includes
Products/ParsedXML, its Expat parser will be used.

Prerequisites
-------------

You need:

- A recent checkout of Zope2; don't forget to run the wo_pcgi.py
  script to compile everything.  (See above -- this is now optional.)

- A recent checkout of the Zope2 product ParsedXML, accessible
  throught /lib/python/Products/ParsedXML; don't forget to run
  the setup.py script to compiles Expat.  (Again, optional.)

- Python 1.5.2; the driver script refuses to work with other versions
  unless you specify the -n option; this is done so that I don't
  accidentally use Python 2.x features.

- Create a .path file containing proper module search path; it should
  point the /lib/python directory that you want to use.

How To Play
-----------

(Don't forget to edit .path, see above!)

The script driver.py takes an XML file with TAL markup as argument and
writes the expanded version to standard output.  The filename argument
defaults to tests/input/test01.xml.

Regression test
---------------

There are unit test suites in the 'tests' subdirectory; these can be
run with tests/run.py.  This should print the testcase names plus
progress info, followed by a final line saying "OK".  It requires that
../unittest.py exists.

There are a number of test files in the 'tests' subdirectory, named
tests/input/test.xml and tests/input/test.html.  The
Python script ./runtest.py calls driver.main() for each test file, and
should print " OK" for each one.  These tests are also run as
part of the unit test suites, so tests/run.py is all you need.

What's Here
-----------

DummyEngine.py		simple-minded TALES execution engine
TALInterpreter.py	class to interpret intermediate code
TALGenerator.py		class to generate intermediate code
XMLParser.py		base class to parse XML, avoiding DOM
TALParser.py		class to parse XML with TAL into intermediate code
HTMLTALParser.py	class to parse HTML with TAL into intermediate code
HTMLParser.py		HTML-parsing base class
driver.py		script to demonstrate TAL expansion
timer.py		script to time various processing phases
setpath.py		hack to set sys.path and import ZODB
__init__.py		empty file that makes this directory a package
runtest.py		Python script to run file-comparison tests
ndiff.py		helper for runtest.py to produce diffs
tests/			drectory with test files and output
tests/run.py		Python script to run all tests

Author and License
------------------

This code is written by Guido van Rossum (project lead), Fred Drake,
and Tim Peters.  It is owned by Digital Creations and can be
redistributed under the Zope Public License.

TO DO
-----

(See also http://www.zope.org/Members/jim/ZPTIssueTracker .)

- Need to remove leading whitespace and newline when omitting an
  element (either through tal:replace with a value of nothing or
  tal:condition with a false condition).

- Empty TAL/METAL attributes are ignored: tal:replace="" is ignored
  rather than causing an error.

- HTMLTALParser.py and TALParser.py are silly names.  Should be
  HTMLTALCompiler.py and XMLTALCompiler.py (or maybe shortened,
  without "TAL"?)

- Should we preserve case of tags and attribute names in HTML?
Zope-2.9.4-retire_zpkg/lib/python/TAL/TALGenerator.py0000644000175000017500000010417010337373524022254 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""
Code generator for TALInterpreter intermediate code.
"""

import re
import cgi

import TALDefs

from TALDefs import NAME_RE, TAL_VERSION
from TALDefs import I18NError, METALError, TALError
from TALDefs import parseSubstitution
from TranslationContext import TranslationContext, DEFAULT_DOMAIN

I18N_REPLACE = 1
I18N_CONTENT = 2
I18N_EXPRESSION = 3

_name_rx = re.compile(NAME_RE)


class TALGenerator:

    inMacroUse = 0
    inMacroDef = 0
    source_file = None

    def __init__(self, expressionCompiler=None, xml=1, source_file=None):
        if not expressionCompiler:
            from DummyEngine import DummyEngine
            expressionCompiler = DummyEngine()
        self.expressionCompiler = expressionCompiler
        self.CompilerError = expressionCompiler.getCompilerError()
        # This holds the emitted opcodes representing the input
        self.program = []
        # The program stack for when we need to do some sub-evaluation for an
        # intermediate result.  E.g. in an i18n:name tag for which the
        # contents describe the ${name} value.
        self.stack = []
        # Another stack of postponed actions.  Elements on this stack are a
        # dictionary; key/values contain useful information that
        # emitEndElement needs to finish its calculations
        self.todoStack = []
        self.macros = {}
        self.slots = {}
        self.slotStack = []
        self.xml = xml
        self.emit("version", TAL_VERSION)
        self.emit("mode", xml and "xml" or "html")
        if source_file is not None:
            self.source_file = source_file
            self.emit("setSourceFile", source_file)
        self.i18nContext = TranslationContext()
        self.i18nLevel = 0

    def getCode(self):
        assert not self.stack
        assert not self.todoStack
        return self.optimize(self.program), self.macros

    def optimize(self, program):
        output = []
        collect = []
        cursor = 0
        if self.xml:
            endsep = "/>"
        else:
            endsep = " />"
        for cursor in xrange(len(program)+1):
            try:
                item = program[cursor]
            except IndexError:
                item = (None, None)
            opcode = item[0]
            if opcode == "rawtext":
                collect.append(item[1])
                continue
            if opcode == "endTag":
                collect.append("" % item[1])
                continue
            if opcode == "startTag":
                if self.optimizeStartTag(collect, item[1], item[2], ">"):
                    continue
            if opcode == "startEndTag":
                if self.optimizeStartTag(collect, item[1], item[2], endsep):
                    continue
            if opcode in ("beginScope", "endScope"):
                # Push *Scope instructions in front of any text instructions;
                # this allows text instructions separated only by *Scope
                # instructions to be joined together.
                output.append(self.optimizeArgsList(item))
                continue
            if opcode == 'noop':
                # This is a spacer for end tags in the face of i18n:name
                # attributes.  We can't let the optimizer collect immediately
                # following end tags into the same rawtextOffset.
                opcode = None
                pass
            text = "".join(collect)
            if text:
                i = text.rfind("\n")
                if i >= 0:
                    i = len(text) - (i + 1)
                    output.append(("rawtextColumn", (text, i)))
                else:
                    output.append(("rawtextOffset", (text, len(text))))
            if opcode != None:
                output.append(self.optimizeArgsList(item))
            collect = []
        return self.optimizeCommonTriple(output)

    def optimizeArgsList(self, item):
        if len(item) == 2:
            return item
        else:
            return item[0], tuple(item[1:])

    # These codes are used to indicate what sort of special actions
    # are needed for each special attribute.  (Simple attributes don't
    # get action codes.)
    #
    # The special actions (which are modal) are handled by
    # TALInterpreter.attrAction() and .attrAction_tal().
    #
    # Each attribute is represented by a tuple:
    #
    # (name, value)                 -- a simple name/value pair, with
    #                                  no special processing
    #
    # (name, value, action, *extra) -- attribute with special
    #                                  processing needs, action is a
    #                                  code that indicates which
    #                                  branch to take, and *extra
    #                                  contains additional,
    #                                  action-specific information
    #                                  needed by the processing
    #
    def optimizeStartTag(self, collect, name, attrlist, end):
        # return true if the tag can be converted to plain text
        if not attrlist:
            collect.append("<%s%s" % (name, end))
            return 1
        opt = 1
        new = ["<" + name]
        for i in range(len(attrlist)):
            item = attrlist[i]
            if len(item) > 2:
                opt = 0
                name, value, action = item[:3]
                attrlist[i] = (name, value, action) + item[3:]
            else:
                if item[1] is None:
                    s = item[0]
                else:
                    s = '%s="%s"' % (item[0], TALDefs.attrEscape(item[1]))
                attrlist[i] = item[0], s
                new.append(" " + s)
        # if no non-optimizable attributes were found, convert to plain text
        if opt:
            new.append(end)
            collect.extend(new)
        return opt

    def optimizeCommonTriple(self, program):
        if len(program) < 3:
            return program
        output = program[:2]
        prev2, prev1 = output
        for item in program[2:]:
            if ( item[0] == "beginScope"
                 and prev1[0] == "setPosition"
                 and prev2[0] == "rawtextColumn"):
                position = output.pop()[1]
                text, column = output.pop()[1]
                prev1 = None, None
                closeprev = 0
                if output and output[-1][0] == "endScope":
                    closeprev = 1
                    output.pop()
                item = ("rawtextBeginScope",
                        (text, column, position, closeprev, item[1]))
            output.append(item)
            prev2 = prev1
            prev1 = item
        return output

    def todoPush(self, todo):
        self.todoStack.append(todo)

    def todoPop(self):
        return self.todoStack.pop()

    def compileExpression(self, expr):
        try:
            return self.expressionCompiler.compile(expr)
        except self.CompilerError, err:
            raise TALError('%s in expression %s' % (err.args[0], `expr`),
                           self.position)

    def pushProgram(self):
        self.stack.append(self.program)
        self.program = []

    def popProgram(self):
        program = self.program
        self.program = self.stack.pop()
        return self.optimize(program)

    def pushSlots(self):
        self.slotStack.append(self.slots)
        self.slots = {}

    def popSlots(self):
        slots = self.slots
        self.slots = self.slotStack.pop()
        return slots

    def emit(self, *instruction):
        self.program.append(instruction)

    def emitStartTag(self, name, attrlist, isend=0):
        if isend:
            opcode = "startEndTag"
        else:
            opcode = "startTag"
        self.emit(opcode, name, attrlist)

    def emitEndTag(self, name):
        if self.xml and self.program and self.program[-1][0] == "startTag":
            # Minimize empty element
            self.program[-1] = ("startEndTag",) + self.program[-1][1:]
        else:
            self.emit("endTag", name)

    def emitOptTag(self, name, optTag, isend):
        program = self.popProgram() #block
        start = self.popProgram() #start tag
        if (isend or not program) and self.xml:
            # Minimize empty element
            start[-1] = ("startEndTag",) + start[-1][1:]
            isend = 1
        cexpr = optTag[0]
        if cexpr:
            cexpr = self.compileExpression(optTag[0])
        self.emit("optTag", name, cexpr, optTag[1], isend, start, program)

    def emitRawText(self, text):
        self.emit("rawtext", text)

    def emitText(self, text):
        self.emitRawText(cgi.escape(text))

    def emitDefines(self, defines):
        for part in TALDefs.splitParts(defines):
            m = re.match(
                r"(?s)\s*(?:(global|local)\s+)?(%s)\s+(.*)\Z" % NAME_RE, part)
            if not m:
                raise TALError("invalid define syntax: " + `part`,
                               self.position)
            scope, name, expr = m.group(1, 2, 3)
            scope = scope or "local"
            cexpr = self.compileExpression(expr)
            if scope == "local":
                self.emit("setLocal", name, cexpr)
            else:
                self.emit("setGlobal", name, cexpr)

    def emitOnError(self, name, onError, TALtag, isend):
        block = self.popProgram()
        key, expr = parseSubstitution(onError)
        cexpr = self.compileExpression(expr)
        if key == "text":
            self.emit("insertText", cexpr, [])
        else:
            assert key == "structure"
            self.emit("insertStructure", cexpr, {}, [])
        if TALtag:
            self.emitOptTag(name, (None, 1), isend)
        else:
            self.emitEndTag(name)
        handler = self.popProgram()
        self.emit("onError", block, handler)

    def emitCondition(self, expr):
        cexpr = self.compileExpression(expr)
        program = self.popProgram()
        self.emit("condition", cexpr, program)

    def emitRepeat(self, arg):
        m = re.match("(?s)\s*(%s)\s+(.*)\Z" % NAME_RE, arg)
        if not m:
            raise TALError("invalid repeat syntax: " + `arg`,
                           self.position)
        name, expr = m.group(1, 2)
        cexpr = self.compileExpression(expr)
        program = self.popProgram()
        self.emit("loop", name, cexpr, program)

    def emitSubstitution(self, arg, attrDict={}):
        key, expr = parseSubstitution(arg)
        cexpr = self.compileExpression(expr)
        program = self.popProgram()
        if key == "text":
            self.emit("insertText", cexpr, program)
        else:
            assert key == "structure"
            self.emit("insertStructure", cexpr, attrDict, program)

    def emitI18nVariable(self, stuff):
        # Used for i18n:name attributes.  arg is extra information describing
        # how the contents of the variable should get filled in, and it will
        # either be a 1-tuple or a 2-tuple.  If arg[0] is None, then the
        # i18n:name value is taken implicitly from the contents of the tag,
        # e.g. "I live in the USA".  In this
        # case, arg[1] is the opcode sub-program describing the contents of
        # the tag.
        #
        # When arg[0] is not None, it contains the tal expression used to
        # calculate the contents of the variable, e.g.
        # "I live in "
        varname, action, expression = stuff
        m = _name_rx.match(varname)
        if m is None or m.group() != varname:
            raise TALError("illegal i18n:name: %r" % varname, self.position)
        key = cexpr = None
        program = self.popProgram()
        if action == I18N_REPLACE:
            # This is a tag with an i18n:name and a tal:replace (implicit or
            # explicit).  Get rid of the first and last elements of the
            # program, which are the start and end tag opcodes of the tag.
            program = program[1:-1]
        elif action == I18N_CONTENT:
            # This is a tag with an i18n:name and a tal:content
            # (explicit-only).  Keep the first and last elements of the
            # program, so we keep the start and end tag output.
            pass
        else:
            assert action == I18N_EXPRESSION
            key, expr = parseSubstitution(expression)
            cexpr = self.compileExpression(expr)
        self.emit('i18nVariable',
                  varname, program, cexpr, int(key == "structure"))

    def emitTranslation(self, msgid, i18ndata):
        program = self.popProgram()
        if i18ndata is None:
            self.emit('insertTranslation', msgid, program)
        else:
            key, expr = parseSubstitution(i18ndata)
            cexpr = self.compileExpression(expr)
            assert key == 'text'
            self.emit('insertTranslation', msgid, program, cexpr)

    def emitDefineMacro(self, macroName):
        program = self.popProgram()
        macroName = macroName.strip()
        if self.macros.has_key(macroName):
            raise METALError("duplicate macro definition: %s" % `macroName`,
                             self.position)
        if not re.match('%s$' % NAME_RE, macroName):
            raise METALError("invalid macro name: %s" % `macroName`,
                             self.position)
        self.macros[macroName] = program
        self.inMacroDef = self.inMacroDef - 1
        self.emit("defineMacro", macroName, program)

    def emitUseMacro(self, expr):
        cexpr = self.compileExpression(expr)
        program = self.popProgram()
        self.inMacroUse = 0
        self.emit("useMacro", expr, cexpr, self.popSlots(), program)

    def emitDefineSlot(self, slotName):
        program = self.popProgram()
        slotName = slotName.strip()
        if not re.match('%s$' % NAME_RE, slotName):
            raise METALError("invalid slot name: %s" % `slotName`,
                             self.position)
        self.emit("defineSlot", slotName, program)

    def emitFillSlot(self, slotName):
        program = self.popProgram()
        slotName = slotName.strip()
        if self.slots.has_key(slotName):
            raise METALError("duplicate fill-slot name: %s" % `slotName`,
                             self.position)
        if not re.match('%s$' % NAME_RE, slotName):
            raise METALError("invalid slot name: %s" % `slotName`,
                             self.position)
        self.slots[slotName] = program
        self.inMacroUse = 1
        self.emit("fillSlot", slotName, program)

    def unEmitWhitespace(self):
        collect = []
        i = len(self.program) - 1
        while i >= 0:
            item = self.program[i]
            if item[0] != "rawtext":
                break
            text = item[1]
            if not re.match(r"\A\s*\Z", text):
                break
            collect.append(text)
            i = i-1
        del self.program[i+1:]
        if i >= 0 and self.program[i][0] == "rawtext":
            text = self.program[i][1]
            m = re.search(r"\s+\Z", text)
            if m:
                self.program[i] = ("rawtext", text[:m.start()])
                collect.append(m.group())
        collect.reverse()
        return "".join(collect)

    def unEmitNewlineWhitespace(self):
        collect = []
        i = len(self.program)
        while i > 0:
            i = i-1
            item = self.program[i]
            if item[0] != "rawtext":
                break
            text = item[1]
            if re.match(r"\A[ \t]*\Z", text):
                collect.append(text)
                continue
            m = re.match(r"(?s)^(.*)(\n[ \t]*)\Z", text)
            if not m:
                break
            text, rest = m.group(1, 2)
            collect.reverse()
            rest = rest + "".join(collect)
            del self.program[i:]
            if text:
                self.emit("rawtext", text)
            return rest
        return None

    def replaceAttrs(self, attrlist, repldict):
        # Each entry in attrlist starts like (name, value).
        # Result is (name, value, action, expr, xlat) if there is a
        # tal:attributes entry for that attribute.  Additional attrs
        # defined only by tal:attributes are added here.
        #
        # (name, value, action, expr, xlat)
        if not repldict:
            return attrlist
        newlist = []
        for item in attrlist:
            key = item[0]
            if repldict.has_key(key):
                expr, xlat, msgid = repldict[key]
                item = item[:2] + ("replace", expr, xlat, msgid)
                del repldict[key]
            newlist.append(item)
        # Add dynamic-only attributes
        for key, (expr, xlat, msgid) in repldict.items():
            newlist.append((key, None, "insert", expr, xlat, msgid))
        return newlist

    def emitStartElement(self, name, attrlist, taldict, metaldict, i18ndict,
                         position=(None, None), isend=0):
        if not taldict and not metaldict and not i18ndict:
            # Handle the simple, common case
            self.emitStartTag(name, attrlist, isend)
            self.todoPush({})
            if isend:
                self.emitEndElement(name, isend)
            return

        self.position = position
        for key, value in taldict.items():
            if key not in TALDefs.KNOWN_TAL_ATTRIBUTES:
                raise TALError("bad TAL attribute: " + `key`, position)
            if not (value or key == 'omit-tag'):
                raise TALError("missing value for TAL attribute: " +
                               `key`, position)
        for key, value in metaldict.items():
            if key not in TALDefs.KNOWN_METAL_ATTRIBUTES:
                raise METALError("bad METAL attribute: " + `key`,
                                 position)
            if not value:
                raise TALError("missing value for METAL attribute: " +
                               `key`, position)
        for key, value in i18ndict.items():
            if key not in TALDefs.KNOWN_I18N_ATTRIBUTES:
                raise I18NError("bad i18n attribute: " + `key`, position)
            if not value and key in ("attributes", "data", "id"):
                raise I18NError("missing value for i18n attribute: " +
                                `key`, position)
        todo = {}
        defineMacro = metaldict.get("define-macro")
        useMacro = metaldict.get("use-macro")
        defineSlot = metaldict.get("define-slot")
        fillSlot = metaldict.get("fill-slot")
        define = taldict.get("define")
        condition = taldict.get("condition")
        repeat = taldict.get("repeat")
        content = taldict.get("content")
        replace = taldict.get("replace")
        attrsubst = taldict.get("attributes")
        onError = taldict.get("on-error")
        omitTag = taldict.get("omit-tag")
        TALtag = taldict.get("tal tag")
        i18nattrs = i18ndict.get("attributes")
        # Preserve empty string if implicit msgids are used.  We'll generate
        # code with the msgid='' and calculate the right implicit msgid during
        # interpretation phase.
        msgid = i18ndict.get("translate")
        varname = i18ndict.get('name')
        i18ndata = i18ndict.get('data')

        if varname and not self.i18nLevel:
            raise I18NError(
                "i18n:name can only occur inside a translation unit",
                position)

        if i18ndata and not msgid:
            raise I18NError("i18n:data must be accompanied by i18n:translate",
                            position)

        if len(metaldict) > 1 and (defineMacro or useMacro):
            raise METALError("define-macro and use-macro cannot be used "
                             "together or with define-slot or fill-slot",
                             position)
        if replace:
            if content:
                raise TALError(
                    "tal:content and tal:replace are mutually exclusive",
                    position)
            if msgid is not None:
                raise I18NError(
                    "i18n:translate and tal:replace are mutually exclusive",
                    position)

        repeatWhitespace = None
        if repeat:
            # Hack to include preceding whitespace in the loop program
            repeatWhitespace = self.unEmitNewlineWhitespace()
        if position != (None, None):
            # XXX at some point we should insist on a non-trivial position
            self.emit("setPosition", position)
        if self.inMacroUse:
            if fillSlot:
                self.pushProgram()
                if self.source_file is not None:
                    self.emit("setSourceFile", self.source_file)
                todo["fillSlot"] = fillSlot
                self.inMacroUse = 0
        else:
            if fillSlot:
                raise METALError("fill-slot must be within a use-macro",
                                 position)
        if not self.inMacroUse:
            if defineMacro:
                self.pushProgram()
                self.emit("version", TAL_VERSION)
                self.emit("mode", self.xml and "xml" or "html")
                if self.source_file is not None:
                    self.emit("setSourceFile", self.source_file)
                todo["defineMacro"] = defineMacro
                self.inMacroDef = self.inMacroDef + 1
            if useMacro:
                self.pushSlots()
                self.pushProgram()
                todo["useMacro"] = useMacro
                self.inMacroUse = 1
            if defineSlot:
                if not self.inMacroDef:
                    raise METALError(
                        "define-slot must be within a define-macro",
                        position)
                self.pushProgram()
                todo["defineSlot"] = defineSlot

        if defineSlot or i18ndict:

            domain = i18ndict.get("domain") or self.i18nContext.domain
            source = i18ndict.get("source") or self.i18nContext.source
            target = i18ndict.get("target") or self.i18nContext.target
            if (  domain != DEFAULT_DOMAIN
                  or source is not None
                  or target is not None):
                self.i18nContext = TranslationContext(self.i18nContext,
                                                      domain=domain,
                                                      source=source,
                                                      target=target)
                self.emit("beginI18nContext",
                          {"domain": domain, "source": source,
                           "target": target})
                todo["i18ncontext"] = 1
        if taldict or i18ndict:
            dict = {}
            for item in attrlist:
                key, value = item[:2]
                dict[key] = value
            self.emit("beginScope", dict)
            todo["scope"] = 1
        if onError:
            self.pushProgram() # handler
            if TALtag:
                self.pushProgram() # start
            self.emitStartTag(name, list(attrlist)) # Must copy attrlist!
            if TALtag:
                self.pushProgram() # start
            self.pushProgram() # block
            todo["onError"] = onError
        if define:
            self.emitDefines(define)
            todo["define"] = define
        if condition:
            self.pushProgram()
            todo["condition"] = condition
        if repeat:
            todo["repeat"] = repeat
            self.pushProgram()
            if repeatWhitespace:
                self.emitText(repeatWhitespace)
        if content:
            if varname:
                todo['i18nvar'] = (varname, I18N_CONTENT, None)
                todo["content"] = content
                self.pushProgram()
            else:
                todo["content"] = content
        elif replace:
            # tal:replace w/ i18n:name has slightly different semantics.  What
            # we're actually replacing then is the contents of the ${name}
            # placeholder.
            if varname:
                todo['i18nvar'] = (varname, I18N_EXPRESSION, replace)
            else:
                todo["replace"] = replace
            self.pushProgram()
        # i18n:name w/o tal:replace uses the content as the interpolation
        # dictionary values
        elif varname:
            todo['i18nvar'] = (varname, I18N_REPLACE, None)
            self.pushProgram()
        if msgid is not None:
            self.i18nLevel += 1
            todo['msgid'] = msgid
        if i18ndata:
            todo['i18ndata'] = i18ndata
        optTag = omitTag is not None or TALtag
        if optTag:
            todo["optional tag"] = omitTag, TALtag
            self.pushProgram()
        if attrsubst or i18nattrs:
            if attrsubst:
                repldict = TALDefs.parseAttributeReplacements(attrsubst,
                                                              self.xml)
            else:
                repldict = {}
            if i18nattrs:
                i18nattrs = _parseI18nAttributes(i18nattrs, attrlist, repldict,
                                                 self.position, self.xml,
                                                 self.source_file)
            else:
                i18nattrs = {}
            # Convert repldict's name-->expr mapping to a
            # name-->(compiled_expr, translate) mapping
            for key, value in repldict.items():
                if i18nattrs.get(key, None):
                    raise I18NError(
                      ("attribute [%s] cannot both be part of tal:attributes" +
                      " and have a msgid in i18n:attributes") % key,
                    position)
                ce = self.compileExpression(value)
                repldict[key] = ce, key in i18nattrs, i18nattrs.get(key)
            for key in i18nattrs:
                if not repldict.has_key(key):
                    repldict[key] = None, 1, i18nattrs.get(key)
        else:
            repldict = {}
        if replace:
            todo["repldict"] = repldict
            repldict = {}
        self.emitStartTag(name, self.replaceAttrs(attrlist, repldict), isend)
        if optTag:
            self.pushProgram()
        if content and not varname:
            self.pushProgram()
        if msgid is not None:
            self.pushProgram()
        if content and varname:
            self.pushProgram()
        if todo and position != (None, None):
            todo["position"] = position
        self.todoPush(todo)
        if isend:
            self.emitEndElement(name, isend)

    def emitEndElement(self, name, isend=0, implied=0):
        todo = self.todoPop()
        if not todo:
            # Shortcut
            if not isend:
                self.emitEndTag(name)
            return

        self.position = position = todo.get("position", (None, None))
        defineMacro = todo.get("defineMacro")
        useMacro = todo.get("useMacro")
        defineSlot = todo.get("defineSlot")
        fillSlot = todo.get("fillSlot")
        repeat = todo.get("repeat")
        content = todo.get("content")
        replace = todo.get("replace")
        condition = todo.get("condition")
        onError = todo.get("onError")
        repldict = todo.get("repldict", {})
        scope = todo.get("scope")
        optTag = todo.get("optional tag")
        msgid = todo.get('msgid')
        i18ncontext = todo.get("i18ncontext")
        varname = todo.get('i18nvar')
        i18ndata = todo.get('i18ndata')

        if implied > 0:
            if defineMacro or useMacro or defineSlot or fillSlot:
                exc = METALError
                what = "METAL"
            else:
                exc = TALError
                what = "TAL"
            raise exc("%s attributes on <%s> require explicit " %
                      (what, name, name), position)

        # If there's no tal:content or tal:replace in the tag with the
        # i18n:name, tal:replace is the default.
        if content:
            self.emitSubstitution(content, {})
        # If we're looking at an implicit msgid, emit the insertTranslation
        # opcode now, so that the end tag doesn't become part of the implicit
        # msgid.  If we're looking at an explicit msgid, it's better to emit
        # the opcode after the i18nVariable opcode so we can better handle
        # tags with both of them in them (and in the latter case, the contents
        # would be thrown away for msgid purposes).
        #
        # Still, we should emit insertTranslation opcode before i18nVariable
        # in case tal:content, i18n:translate and i18n:name in the same tag
        if msgid is not None:
            if (not varname) or (
                varname and (varname[1] == I18N_CONTENT)):
                self.emitTranslation(msgid, i18ndata)
            self.i18nLevel -= 1
        if optTag:
            self.emitOptTag(name, optTag, isend)
        elif not isend:
            # If we're processing the end tag for a tag that contained
            # i18n:name, we need to make sure that optimize() won't collect
            # immediately following end tags into the same rawtextOffset, so
            # put a spacer here that the optimizer will recognize.
            if varname:
                self.emit('noop')
            self.emitEndTag(name)
        # If i18n:name appeared in the same tag as tal:replace then we're
        # going to do the substitution a little bit differently.  The results
        # of the expression go into the i18n substitution dictionary.
        if replace:
            self.emitSubstitution(replace, repldict)
        elif varname:
            # o varname[0] is the variable name
            # o varname[1] is either
            #   - I18N_REPLACE for implicit tal:replace
            #   - I18N_CONTENT for tal:content
            #   - I18N_EXPRESSION for explicit tal:replace
            # o varname[2] will be None for the first two actions and the
            #   replacement tal expression for the third action.  This
            #   can include a 'text' or 'structure' indicator.
            assert (varname[1]
                    in [I18N_REPLACE, I18N_CONTENT, I18N_EXPRESSION])
            self.emitI18nVariable(varname)
        # Do not test for "msgid is not None", i.e. we only want to test for
        # explicit msgids here.  See comment above.
        if msgid is not None: 
            # in case tal:content, i18n:translate and i18n:name in the
            # same tag insertTranslation opcode has already been
            # emitted
            if varname and (varname[1] <> I18N_CONTENT):
                self.emitTranslation(msgid, i18ndata)
        if repeat:
            self.emitRepeat(repeat)
        if condition:
            self.emitCondition(condition)
        if onError:
            self.emitOnError(name, onError, optTag and optTag[1], isend)
        if scope:
            self.emit("endScope")
        if i18ncontext:
            self.emit("endI18nContext")
            assert self.i18nContext.parent is not None
            self.i18nContext = self.i18nContext.parent
        if defineSlot:
            self.emitDefineSlot(defineSlot)
        if fillSlot:
            self.emitFillSlot(fillSlot)
        if useMacro:
            self.emitUseMacro(useMacro)
        if defineMacro:
            self.emitDefineMacro(defineMacro)


def _parseI18nAttributes(i18nattrs, attrlist, repldict, position,
                         xml, source_file):

    def addAttribute(dic, attr, msgid, position, xml):
        if not xml:
            attr = attr.lower()
        if attr in dic:
            raise TALError(
                "attribute may only be specified once in i18n:attributes: "
                + attr,
                position)
        dic[attr] = msgid

    d = {}
    if ';' in i18nattrs:
        i18nattrlist = i18nattrs.split(';')
        i18nattrlist = [attr.strip().split() 
                        for attr in i18nattrlist if attr.strip()]
        for parts in i18nattrlist:
            if len(parts) > 2:
                raise TALError("illegal i18n:attributes specification: %r"
                                % parts, position)
            if len(parts) == 2:
                attr, msgid = parts
            else:
                # len(parts) == 1
                attr = parts[0]
                msgid = None
            addAttribute(d, attr, msgid, position, xml)
    else:
        i18nattrlist = i18nattrs.split()
        if len(i18nattrlist) == 1:
            addAttribute(d, i18nattrlist[0], None, position, xml)
        elif len(i18nattrlist) == 2:
            staticattrs = [attr[0] for attr in attrlist if len(attr) == 2]
            if (not i18nattrlist[1] in staticattrs) and (
                not i18nattrlist[1] in repldict):
                attr, msgid = i18nattrlist
                addAttribute(d, attr, msgid, position, xml)    
            else:
                import warnings
                warnings.warn(I18N_ATTRIBUTES_WARNING
                % (source_file, str(position), i18nattrs)
                , DeprecationWarning)
                msgid = None
                for attr in i18nattrlist:
                    addAttribute(d, attr, msgid, position, xml)    
        else:    
            import warnings
            warnings.warn(I18N_ATTRIBUTES_WARNING
            % (source_file, str(position), i18nattrs)
            , DeprecationWarning)
            msgid = None
            for attr in i18nattrlist:
                addAttribute(d, attr, msgid, position, xml)    
    return d

I18N_ATTRIBUTES_WARNING = (
    'Space separated attributes in i18n:attributes'
    ' are deprecated (i18n:attributes="value title"). Please use'
    ' semicolon to separate attributes'
    ' (i18n:attributes="value; title").'
    '\nFile %s at row, column %s\nAttributes %s')

def test():
    t = TALGenerator()
    t.pushProgram()
    t.emit("bar")
    p = t.popProgram()
    t.emit("foo", p)

if __name__ == "__main__":
    test()
Zope-2.9.4-retire_zpkg/lib/python/TAL/ndiff.py0000644000175000017500000005771510050234363021054 0ustar  tseavertseaver#! /usr/bin/env python

# Module ndiff version 1.6.0
# Released to the public domain 08-Dec-2000,
# by Tim Peters (tim.one@home.com).

# Provided as-is; use at your own risk; no warranty; no promises; enjoy!

"""ndiff [-q] file1 file2
    or
ndiff (-r1 | -r2) < ndiff_output > file1_or_file2

Print a human-friendly file difference report to stdout.  Both inter-
and intra-line differences are noted.  In the second form, recreate file1
(-r1) or file2 (-r2) on stdout, from an ndiff report on stdin.

In the first form, if -q ("quiet") is not specified, the first two lines
of output are

-: file1
+: file2

Each remaining line begins with a two-letter code:

    "- "    line unique to file1
    "+ "    line unique to file2
    "  "    line common to both files
    "? "    line not present in either input file

Lines beginning with "? " attempt to guide the eye to intraline
differences, and were not present in either input file.  These lines can be
confusing if the source files contain tab characters.

The first file can be recovered by retaining only lines that begin with
"  " or "- ", and deleting those 2-character prefixes; use ndiff with -r1.

The second file can be recovered similarly, but by retaining only "  " and
"+ " lines; use ndiff with -r2; or, on Unix, the second file can be
recovered by piping the output through

    sed -n '/^[+ ] /s/^..//p'

See module comments for details and programmatic interface.
"""

__version__ = 1, 5, 0

# SequenceMatcher tries to compute a "human-friendly diff" between
# two sequences (chiefly picturing a file as a sequence of lines,
# and a line as a sequence of characters, here).  Unlike e.g. UNIX(tm)
# diff, the fundamental notion is the longest *contiguous* & junk-free
# matching subsequence.  That's what catches peoples' eyes.  The
# Windows(tm) windiff has another interesting notion, pairing up elements
# that appear uniquely in each sequence.  That, and the method here,
# appear to yield more intuitive difference reports than does diff.  This
# method appears to be the least vulnerable to synching up on blocks
# of "junk lines", though (like blank lines in ordinary text files,
# or maybe "
" lines in HTML files).  That may be because this is
# the only method of the 3 that has a *concept* of "junk" .
#
# Note that ndiff makes no claim to produce a *minimal* diff.  To the
# contrary, minimal diffs are often counter-intuitive, because they
# synch up anywhere possible, sometimes accidental matches 100 pages
# apart.  Restricting synch points to contiguous matches preserves some
# notion of locality, at the occasional cost of producing a longer diff.
#
# With respect to junk, an earlier version of ndiff simply refused to
# *start* a match with a junk element.  The result was cases like this:
#     before: private Thread currentThread;
#     after:  private volatile Thread currentThread;
# If you consider whitespace to be junk, the longest contiguous match
# not starting with junk is "e Thread currentThread".  So ndiff reported
# that "e volatil" was inserted between the 't' and the 'e' in "private".
# While an accurate view, to people that's absurd.  The current version
# looks for matching blocks that are entirely junk-free, then extends the
# longest one of those as far as possible but only with matching junk.
# So now "currentThread" is matched, then extended to suck up the
# preceding blank; then "private" is matched, and extended to suck up the
# following blank; then "Thread" is matched; and finally ndiff reports
# that "volatile " was inserted before "Thread".  The only quibble
# remaining is that perhaps it was really the case that " volatile"
# was inserted after "private".  I can live with that .
#
# NOTE on junk:  the module-level names
#    IS_LINE_JUNK
#    IS_CHARACTER_JUNK
# can be set to any functions you like.  The first one should accept
# a single string argument, and return true iff the string is junk.
# The default is whether the regexp r"\s*#?\s*$" matches (i.e., a
# line without visible characters, except for at most one splat).
# The second should accept a string of length 1 etc.  The default is
# whether the character is a blank or tab (note: bad idea to include
# newline in this!).
#
# After setting those, you can call fcompare(f1name, f2name) with the
# names of the files you want to compare.  The difference report
# is sent to stdout.  Or you can call main(args), passing what would
# have been in sys.argv[1:] had the cmd-line form been used.

TRACE = 0

# define what "junk" means
import re

def IS_LINE_JUNK(line, pat=re.compile(r"\s*#?\s*$").match):
    return pat(line) is not None

def IS_CHARACTER_JUNK(ch, ws=" \t"):
    return ch in ws

del re

class SequenceMatcher:
    def __init__(self, isjunk=None, a='', b=''):
        # Members:
        # a
        #      first sequence
        # b
        #      second sequence; differences are computed as "what do
        #      we need to do to 'a' to change it into 'b'?"
        # b2j
        #      for x in b, b2j[x] is a list of the indices (into b)
        #      at which x appears; junk elements do not appear
        # b2jhas
        #      b2j.has_key
        # fullbcount
        #      for x in b, fullbcount[x] == the number of times x
        #      appears in b; only materialized if really needed (used
        #      only for computing quick_ratio())
        # matching_blocks
        #      a list of (i, j, k) triples, where a[i:i+k] == b[j:j+k];
        #      ascending & non-overlapping in i and in j; terminated by
        #      a dummy (len(a), len(b), 0) sentinel
        # opcodes
        #      a list of (tag, i1, i2, j1, j2) tuples, where tag is
        #      one of
        #          'replace'   a[i1:i2] should be replaced by b[j1:j2]
        #          'delete'    a[i1:i2] should be deleted
        #          'insert'    b[j1:j2] should be inserted
        #          'equal'     a[i1:i2] == b[j1:j2]
        # isjunk
        #      a user-supplied function taking a sequence element and
        #      returning true iff the element is "junk" -- this has
        #      subtle but helpful effects on the algorithm, which I'll
        #      get around to writing up someday <0.9 wink>.
        #      DON'T USE!  Only __chain_b uses this.  Use isbjunk.
        # isbjunk
        #      for x in b, isbjunk(x) == isjunk(x) but much faster;
        #      it's really the has_key method of a hidden dict.
        #      DOES NOT WORK for x in a!

        self.isjunk = isjunk
        self.a = self.b = None
        self.set_seqs(a, b)

    def set_seqs(self, a, b):
        self.set_seq1(a)
        self.set_seq2(b)

    def set_seq1(self, a):
        if a is self.a:
            return
        self.a = a
        self.matching_blocks = self.opcodes = None

    def set_seq2(self, b):
        if b is self.b:
            return
        self.b = b
        self.matching_blocks = self.opcodes = None
        self.fullbcount = None
        self.__chain_b()

    # For each element x in b, set b2j[x] to a list of the indices in
    # b where x appears; the indices are in increasing order; note that
    # the number of times x appears in b is len(b2j[x]) ...
    # when self.isjunk is defined, junk elements don't show up in this
    # map at all, which stops the central find_longest_match method
    # from starting any matching block at a junk element ...
    # also creates the fast isbjunk function ...
    # note that this is only called when b changes; so for cross-product
    # kinds of matches, it's best to call set_seq2 once, then set_seq1
    # repeatedly

    def __chain_b(self):
        # Because isjunk is a user-defined (not C) function, and we test
        # for junk a LOT, it's important to minimize the number of calls.
        # Before the tricks described here, __chain_b was by far the most
        # time-consuming routine in the whole module!  If anyone sees
        # Jim Roskind, thank him again for profile.py -- I never would
        # have guessed that.
        # The first trick is to build b2j ignoring the possibility
        # of junk.  I.e., we don't call isjunk at all yet.  Throwing
        # out the junk later is much cheaper than building b2j "right"
        # from the start.
        b = self.b
        self.b2j = b2j = {}
        self.b2jhas = b2jhas = b2j.has_key
        for i in xrange(len(b)):
            elt = b[i]
            if b2jhas(elt):
                b2j[elt].append(i)
            else:
                b2j[elt] = [i]

        # Now b2j.keys() contains elements uniquely, and especially when
        # the sequence is a string, that's usually a good deal smaller
        # than len(string).  The difference is the number of isjunk calls
        # saved.
        isjunk, junkdict = self.isjunk, {}
        if isjunk:
            for elt in b2j.keys():
                if isjunk(elt):
                    junkdict[elt] = 1   # value irrelevant; it's a set
                    del b2j[elt]

        # Now for x in b, isjunk(x) == junkdict.has_key(x), but the
        # latter is much faster.  Note too that while there may be a
        # lot of junk in the sequence, the number of *unique* junk
        # elements is probably small.  So the memory burden of keeping
        # this dict alive is likely trivial compared to the size of b2j.
        self.isbjunk = junkdict.has_key

    def find_longest_match(self, alo, ahi, blo, bhi):
        """Find longest matching block in a[alo:ahi] and b[blo:bhi].

        If isjunk is not defined:

        Return (i,j,k) such that a[i:i+k] is equal to b[j:j+k], where
            alo <= i <= i+k <= ahi
            blo <= j <= j+k <= bhi
        and for all (i',j',k') meeting those conditions,
            k >= k'
            i <= i'
            and if i == i', j <= j'
        In other words, of all maximal matching blocks, return one
        that starts earliest in a, and of all those maximal matching
        blocks that start earliest in a, return the one that starts
        earliest in b.

        If isjunk is defined, first the longest matching block is
        determined as above, but with the additional restriction that
        no junk element appears in the block.  Then that block is
        extended as far as possible by matching (only) junk elements on
        both sides.  So the resulting block never matches on junk except
        as identical junk happens to be adjacent to an "interesting"
        match.

        If no blocks match, return (alo, blo, 0).
        """

        # CAUTION:  stripping common prefix or suffix would be incorrect.
        # E.g.,
        #    ab
        #    acab
        # Longest matching block is "ab", but if common prefix is
        # stripped, it's "a" (tied with "b").  UNIX(tm) diff does so
        # strip, so ends up claiming that ab is changed to acab by
        # inserting "ca" in the middle.  That's minimal but unintuitive:
        # "it's obvious" that someone inserted "ac" at the front.
        # Windiff ends up at the same place as diff, but by pairing up
        # the unique 'b's and then matching the first two 'a's.

        a, b, b2j, isbjunk = self.a, self.b, self.b2j, self.isbjunk
        besti, bestj, bestsize = alo, blo, 0
        # find longest junk-free match
        # during an iteration of the loop, j2len[j] = length of longest
        # junk-free match ending with a[i-1] and b[j]
        j2len = {}
        nothing = []
        for i in xrange(alo, ahi):
            # look at all instances of a[i] in b; note that because
            # b2j has no junk keys, the loop is skipped if a[i] is junk
            j2lenget = j2len.get
            newj2len = {}
            for j in b2j.get(a[i], nothing):
                # a[i] matches b[j]
                if j < blo:
                    continue
                if j >= bhi:
                    break
                k = newj2len[j] = j2lenget(j-1, 0) + 1
                if k > bestsize:
                    besti, bestj, bestsize = i-k+1, j-k+1, k
            j2len = newj2len

        # Now that we have a wholly interesting match (albeit possibly
        # empty!), we may as well suck up the matching junk on each
        # side of it too.  Can't think of a good reason not to, and it
        # saves post-processing the (possibly considerable) expense of
        # figuring out what to do with it.  In the case of an empty
        # interesting match, this is clearly the right thing to do,
        # because no other kind of match is possible in the regions.
        while besti > alo and bestj > blo and \
              isbjunk(b[bestj-1]) and \
              a[besti-1] == b[bestj-1]:
            besti, bestj, bestsize = besti-1, bestj-1, bestsize+1
        while besti+bestsize < ahi and bestj+bestsize < bhi and \
              isbjunk(b[bestj+bestsize]) and \
              a[besti+bestsize] == b[bestj+bestsize]:
            bestsize = bestsize + 1

        if TRACE:
            print "get_matching_blocks", alo, ahi, blo, bhi
            print "    returns", besti, bestj, bestsize
        return besti, bestj, bestsize

    def get_matching_blocks(self):
        if self.matching_blocks is not None:
            return self.matching_blocks
        self.matching_blocks = []
        la, lb = len(self.a), len(self.b)
        self.__helper(0, la, 0, lb, self.matching_blocks)
        self.matching_blocks.append( (la, lb, 0) )
        if TRACE:
            print '*** matching blocks', self.matching_blocks
        return self.matching_blocks

    # builds list of matching blocks covering a[alo:ahi] and
    # b[blo:bhi], appending them in increasing order to answer

    def __helper(self, alo, ahi, blo, bhi, answer):
        i, j, k = x = self.find_longest_match(alo, ahi, blo, bhi)
        # a[alo:i] vs b[blo:j] unknown
        # a[i:i+k] same as b[j:j+k]
        # a[i+k:ahi] vs b[j+k:bhi] unknown
        if k:
            if alo < i and blo < j:
                self.__helper(alo, i, blo, j, answer)
            answer.append(x)
            if i+k < ahi and j+k < bhi:
                self.__helper(i+k, ahi, j+k, bhi, answer)

    def ratio(self):
        """Return a measure of the sequences' similarity (float in [0,1]).

        Where T is the total number of elements in both sequences, and
        M is the number of matches, this is 2*M / T.
        Note that this is 1 if the sequences are identical, and 0 if
        they have nothing in common.
        """

        matches = reduce(lambda sum, triple: sum + triple[-1],
                         self.get_matching_blocks(), 0)
        return 2.0 * matches / (len(self.a) + len(self.b))

    def quick_ratio(self):
        """Return an upper bound on ratio() relatively quickly."""
        # viewing a and b as multisets, set matches to the cardinality
        # of their intersection; this counts the number of matches
        # without regard to order, so is clearly an upper bound
        if self.fullbcount is None:
            self.fullbcount = fullbcount = {}
            for elt in self.b:
                fullbcount[elt] = fullbcount.get(elt, 0) + 1
        fullbcount = self.fullbcount
        # avail[x] is the number of times x appears in 'b' less the
        # number of times we've seen it in 'a' so far ... kinda
        avail = {}
        availhas, matches = avail.has_key, 0
        for elt in self.a:
            if availhas(elt):
                numb = avail[elt]
            else:
                numb = fullbcount.get(elt, 0)
            avail[elt] = numb - 1
            if numb > 0:
                matches = matches + 1
        return 2.0 * matches / (len(self.a) + len(self.b))

    def real_quick_ratio(self):
        """Return an upper bound on ratio() very quickly"""
        la, lb = len(self.a), len(self.b)
        # can't have more matches than the number of elements in the
        # shorter sequence
        return 2.0 * min(la, lb) / (la + lb)

    def get_opcodes(self):
        if self.opcodes is not None:
            return self.opcodes
        i = j = 0
        self.opcodes = answer = []
        for ai, bj, size in self.get_matching_blocks():
            # invariant:  we've pumped out correct diffs to change
            # a[:i] into b[:j], and the next matching block is
            # a[ai:ai+size] == b[bj:bj+size].  So we need to pump
            # out a diff to change a[i:ai] into b[j:bj], pump out
            # the matching block, and move (i,j) beyond the match
            tag = ''
            if i < ai and j < bj:
                tag = 'replace'
            elif i < ai:
                tag = 'delete'
            elif j < bj:
                tag = 'insert'
            if tag:
                answer.append( (tag, i, ai, j, bj) )
            i, j = ai+size, bj+size
            # the list of matching blocks is terminated by a
            # sentinel with size 0
            if size:
                answer.append( ('equal', ai, i, bj, j) )
        return answer

# meant for dumping lines
def dump(tag, x, lo, hi):
    for i in xrange(lo, hi):
        print tag, x[i],

def plain_replace(a, alo, ahi, b, blo, bhi):
    assert alo < ahi and blo < bhi
    # dump the shorter block first -- reduces the burden on short-term
    # memory if the blocks are of very different sizes
    if bhi - blo < ahi - alo:
        dump('+', b, blo, bhi)
        dump('-', a, alo, ahi)
    else:
        dump('-', a, alo, ahi)
        dump('+', b, blo, bhi)

# When replacing one block of lines with another, this guy searches
# the blocks for *similar* lines; the best-matching pair (if any) is
# used as a synch point, and intraline difference marking is done on
# the similar pair.  Lots of work, but often worth it.

def fancy_replace(a, alo, ahi, b, blo, bhi):
    if TRACE:
        print '*** fancy_replace', alo, ahi, blo, bhi
        dump('>', a, alo, ahi)
        dump('<', b, blo, bhi)

    # don't synch up unless the lines have a similarity score of at
    # least cutoff; best_ratio tracks the best score seen so far
    best_ratio, cutoff = 0.74, 0.75
    cruncher = SequenceMatcher(IS_CHARACTER_JUNK)
    eqi, eqj = None, None   # 1st indices of equal lines (if any)

    # search for the pair that matches best without being identical
    # (identical lines must be junk lines, & we don't want to synch up
    # on junk -- unless we have to)
    for j in xrange(blo, bhi):
        bj = b[j]
        cruncher.set_seq2(bj)
        for i in xrange(alo, ahi):
            ai = a[i]
            if ai == bj:
                if eqi is None:
                    eqi, eqj = i, j
                continue
            cruncher.set_seq1(ai)
            # computing similarity is expensive, so use the quick
            # upper bounds first -- have seen this speed up messy
            # compares by a factor of 3.
            # note that ratio() is only expensive to compute the first
            # time it's called on a sequence pair; the expensive part
            # of the computation is cached by cruncher
            if cruncher.real_quick_ratio() > best_ratio and \
                  cruncher.quick_ratio() > best_ratio and \
                  cruncher.ratio() > best_ratio:
                best_ratio, best_i, best_j = cruncher.ratio(), i, j
    if best_ratio < cutoff:
        # no non-identical "pretty close" pair
        if eqi is None:
            # no identical pair either -- treat it as a straight replace
            plain_replace(a, alo, ahi, b, blo, bhi)
            return
        # no close pair, but an identical pair -- synch up on that
        best_i, best_j, best_ratio = eqi, eqj, 1.0
    else:
        # there's a close pair, so forget the identical pair (if any)
        eqi = None

    # a[best_i] very similar to b[best_j]; eqi is None iff they're not
    # identical
    if TRACE:
        print '*** best_ratio', best_ratio, best_i, best_j
        dump('>', a, best_i, best_i+1)
        dump('<', b, best_j, best_j+1)

    # pump out diffs from before the synch point
    fancy_helper(a, alo, best_i, b, blo, best_j)

    # do intraline marking on the synch pair
    aelt, belt = a[best_i], b[best_j]
    if eqi is None:
        # pump out a '-', '?', '+', '?' quad for the synched lines
        atags = btags = ""
        cruncher.set_seqs(aelt, belt)
        for tag, ai1, ai2, bj1, bj2 in cruncher.get_opcodes():
            la, lb = ai2 - ai1, bj2 - bj1
            if tag == 'replace':
                atags = atags + '^' * la
                btags = btags + '^' * lb
            elif tag == 'delete':
                atags = atags + '-' * la
            elif tag == 'insert':
                btags = btags + '+' * lb
            elif tag == 'equal':
                atags = atags + ' ' * la
                btags = btags + ' ' * lb
            else:
                raise ValueError, 'unknown tag ' + `tag`
        printq(aelt, belt, atags, btags)
    else:
        # the synch pair is identical
        print ' ', aelt,

    # pump out diffs from after the synch point
    fancy_helper(a, best_i+1, ahi, b, best_j+1, bhi)

def fancy_helper(a, alo, ahi, b, blo, bhi):
    if alo < ahi:
        if blo < bhi:
            fancy_replace(a, alo, ahi, b, blo, bhi)
        else:
            dump('-', a, alo, ahi)
    elif blo < bhi:
        dump('+', b, blo, bhi)

# Crap to deal with leading tabs in "?" output.  Can hurt, but will
# probably help most of the time.

def printq(aline, bline, atags, btags):
    common = min(count_leading(aline, "\t"),
                 count_leading(bline, "\t"))
    common = min(common, count_leading(atags[:common], " "))
    print "-", aline,
    if count_leading(atags, " ") < len(atags):
        print "?", "\t" * common + atags[common:]
    print "+", bline,
    if count_leading(btags, " ") < len(btags):
        print "?", "\t" * common + btags[common:]

def count_leading(line, ch):
    i, n = 0, len(line)
    while i < n and line[i] == ch:
        i = i + 1
    return i

def fail(msg):
    import sys
    out = sys.stderr.write
    out(msg + "\n\n")
    out(__doc__)
    return 0

# open a file & return the file object; gripe and return 0 if it
# couldn't be opened
def fopen(fname):
    try:
        return open(fname, 'r')
    except IOError, detail:
        return fail("couldn't open " + fname + ": " + str(detail))

# open two files & spray the diff to stdout; return false iff a problem
def fcompare(f1name, f2name):
    f1 = fopen(f1name)
    f2 = fopen(f2name)
    if not f1 or not f2:
        return 0

    a = f1.readlines(); f1.close()
    b = f2.readlines(); f2.close()

    cruncher = SequenceMatcher(IS_LINE_JUNK, a, b)
    for tag, alo, ahi, blo, bhi in cruncher.get_opcodes():
        if tag == 'replace':
            fancy_replace(a, alo, ahi, b, blo, bhi)
        elif tag == 'delete':
            dump('-', a, alo, ahi)
        elif tag == 'insert':
            dump('+', b, blo, bhi)
        elif tag == 'equal':
            dump(' ', a, alo, ahi)
        else:
            raise ValueError, 'unknown tag ' + `tag`

    return 1

# crack args (sys.argv[1:] is normal) & compare;
# return false iff a problem

def main(args):
    import getopt
    try:
        opts, args = getopt.getopt(args, "qr:")
    except getopt.error, detail:
        return fail(str(detail))
    noisy = 1
    qseen = rseen = 0
    for opt, val in opts:
        if opt == "-q":
            qseen = 1
            noisy = 0
        elif opt == "-r":
            rseen = 1
            whichfile = val
    if qseen and rseen:
        return fail("can't specify both -q and -r")
    if rseen:
        if args:
            return fail("no args allowed with -r option")
        if whichfile in "12":
            restore(whichfile)
            return 1
        return fail("-r value must be 1 or 2")
    if len(args) != 2:
        return fail("need 2 filename args")
    f1name, f2name = args
    if noisy:
        print '-:', f1name
        print '+:', f2name
    return fcompare(f1name, f2name)

def restore(which):
    import sys
    tag = {"1": "- ", "2": "+ "}[which]
    prefixes = ("  ", tag)
    for line in sys.stdin.readlines():
        if line[:2] in prefixes:
            print line[2:],

if __name__ == '__main__':
    import sys
    args = sys.argv[1:]
    if "-profile" in args:
        import profile, pstats
        args.remove("-profile")
        statf = "ndiff.pro"
        profile.run("main(args)", statf)
        stats = pstats.Stats(statf)
        stats.strip_dirs().sort_stats('time').print_stats()
    else:
        main(args)
Zope-2.9.4-retire_zpkg/lib/python/Globals/0000755000175000017500000000000010447233607020352 5ustar  tseavertseaverZope-2.9.4-retire_zpkg/lib/python/Globals/__init__.py0000755000175000017500000000311710340122303022446 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

"""Global definitions"""

__version__='$Revision: 1.56 $'[11:-2]

# Global constants: __replaceable__ flags:
NOT_REPLACEABLE = 0
REPLACEABLE = 1
UNIQUE = 2

import Acquisition, ComputedAttribute, App.PersistentExtra, os
import TreeDisplay

from App.Common import package_home, attrget, Dictionary
from App.config import getConfiguration as _getConfiguration
from Persistence import Persistent, PersistentMapping
from App.special_dtml import HTML, HTMLFile, DTMLFile
from App.class_init import default__class_init__, ApplicationDefaultPermissions

# Nicer alias for class initializer.
InitializeClass = default__class_init__

from App.Dialogs import MessageDialog
from App.ImageFile import ImageFile

VersionNameName='Zope-Version'

_cfg = _getConfiguration()
data_dir = _cfg.clienthome

# backward compatibility
INSTANCE_HOME = _cfg.instancehome
SOFTWARE_HOME = _cfg.softwarehome
ZOPE_HOME = _cfg.zopehome

opened=[]

DevelopmentMode=_cfg.debug_mode

del _cfg, _getConfiguration

Zope-2.9.4-retire_zpkg/lib/python/App/0000755000175000017500000000000010447233616017507 5ustar  tseavertseaverZope-2.9.4-retire_zpkg/lib/python/App/www/0000755000175000017500000000000010447233616020333 5ustar  tseavertseaverZope-2.9.4-retire_zpkg/lib/python/App/www/border.gif0000755000175000017500000000163210050234363022272 0ustar  tseavertseaverGIF89a			





   !!!"""###$$$%%%&&&'''((()))***+++,,,---...///000111222333444555666777888999:::;;;<<<===>>>???@@@AAABBBCCCDDDEEEFFFGGGHHHIIIJJJKKKLLLMMMNNNOOOPPPQQQRRRSSSTTTUUUVVVWWWXXXYYYZZZ[[[\\\]]]^^^___```aaabbbcccdddeeefffggghhhiiijjjkkklllmmmnnnooopppqqqrrrssstttuuuvvvwwwxxxyyyzzz{{{|||}}}~~~!,wߝHp*LpÆJHq{(em࿏ CIɓ(S\ɲ˗0cʜI͛8sɳϟ@
JQZTtӦPaѫXjʵׯ`ÊKY;Zope-2.9.4-retire_zpkg/lib/python/App/www/logo.jpg0000755000175000017500000000630310050234363021770 0ustar  tseavertseaverJFIFC	!"$"$C6f"	
}!1AQa"q2#BR$3br	
%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz	
w!1AQaq"2B	#3Rbr
$4%&'()*56789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz?7$.aj0٘M<wmݯ5KicPp
++P,q*u{nzKtr~9;q$;bhssί,u^	F|V,"k_:Me+n>uaz_&iFICzrf,FuGZeb_`mjP2Ha^|٬#$(a_o/4
m$fҧ{<+c0+U'WẒt8#34b;LGM_ͿAW۶fIhuMH׈XiVSK2.Qr,*Q;n旷k[Z~%q$)!=ŝ;
B7u9BRN-nw:Ot,IљU`9wqk1M264}o\3hٟKR]ol^iupi0,Ig”Uf7yr:jz,>ILGRpM`ŶPX+ϩ^5Q5=A?綷lUƥbc;V8о8w:m>!x&U /d 'r(&h$ޟ{[O]5Fc#LCye`PqV^Vd]:U=Ya|֑JQ&|:33sI,ؗG
%r\Ɨ,shV\_?(83k)zu=|<-G#uy?
xrSiR%pI-@p6Vn9;q:T[M݂QI'^/׹Ӽy|A\kpz=+oAo9U*3طkx:݂]e/2`wpּN]TK+-W%Gl'ֻ_,|-Ic\>iTrYXaXƽIP]Z2Qw1/,a_ﺁ^kN=@/uy'Tյۻ}\YiVs8
2F[\iGndHt?ݓF
bvI՞&f@,bIO&Xd.svO/kzTFK.W-&ywr$# Xlqdlz|Ͻa^P}t[VR/q lNӏws~<
=G[}woAu4ϊ:Ӭᴵ,PE<*F8fmH yx,e|^UWj"XÈUtp#WQW,
U{I+ϋOXV$M?%( ؈IEoV6Zope-2.9.4-retire_zpkg/lib/python/App/www/DebugManager_icon.gif0000755000175000017500000000156610050234363024354 0ustar  tseavertseaverGIF89aPPP@@@@@!,SH`*L!ÆA3J$b,Ԉ$K9P$ʔ	0F]\ip&͚[B,sĆ;Zope-2.9.4-retire_zpkg/lib/python/App/www/productFolder.gif0000644000175000017500000000163710050234363023633 0ustar  tseavertseaverGIF89aPPP@@@@@!,|H A,(
hb‹,xǏL|@S. R&<@%ˑ%O"Ise˗%kb̓'}Lyt(.ʜ*PBSZR%TŠVhӪE  ;Zope-2.9.4-retire_zpkg/lib/python/App/www/undo_icon.gif0000755000175000017500000000154010050234363022770 0ustar  tseavertseaverGIF89aPPP@@@@@!,=HLhCF(Paŋ-Z1Ɗȍ!)f|2A%_X0 ;Zope-2.9.4-retire_zpkg/lib/python/App/www/vManage.gif0000755000175000017500000000154310050234363022374 0ustar  tseavertseaverGIF89aPPP@@@@@!,@HDXa4ĉ^qcE	?4"5bHrG,;*4I;Zope-2.9.4-retire_zpkg/lib/python/App/www/z_button.jpg0000644000175000017500000000461510050234363022675 0ustar  tseavertseaverJFIFHHC	!"$"$CMN"	A		!1AQ"aq	2R$3bcr#&BDdt,!12AQaq?2}ζr_xŒ(Me :@z k=&3Ńٓ3)+u$u%GRwjr4z
ilRGs7V݊ׯtLjD$C+_6jҚJm;Rp|bqU@o1{BppvU5(JӅjiשY>SIj}6i8,k}bSfW\-J{D6w6HMsC$+|X'QֳhӖfߑEƂQ¯phdzWVvZx~8\!Օ%7ơhu>8=ح\w>̘ɎeԅI# M^qW*piP\BTλX߭Ϩ\ICWu
w6yq(ߤr1mΔ=_sa-cޮn
] Nq!}kW3`it~!,(6[Nˠu&):Hq+cSZHWVi 3NjZB2|u=*!:j}l6%p#*$
W[J7JxHӅ<c;RWVjPR zϙ龿TX2KqJ<YSS quχ^Y׾KV6zŷ=~Xm}bK
0'Flτhͩ?939'9Y'NV
6EKf6MY=I''̒O:$w
 Zë2۷jl#UwvIOE1@u^l7T)0aCFdnf!)$:Fn͹8[BN~j54Ҝ5ԔS	sz.~_̮0~ՈH*4N2Tđ)iK.DF!QKhO2z{jI)PD6Vut}[J$!ȈH#(4Ir7Q)5r鈚8c)„c	#GQR۶?YP9
0Z\"%8>V6A]GNܮ0(&uGYMR" JFIFHH'File written by Adobe Photoshop 4.0Adobed			



7"?	
	
3!1AQa"q2B#$Rb34rC%Scs5&DTdE£t6UeuF'Vfv7GWgw5!1AQaq"2B#R3$brCScs4%&5DTdEU6teuFVfv'7GWgw?~}Xվu'
m}?9uU{^=U?Vq[~wG+ǯp]ګԎ\=^M8x߼Uc}M^~Ε:uOenͿW4vcGS2sܯ'V8xP8~}:5=SztNsG-ZWՊ;+'*Hj_Kz]mq.E.1
}m~O̯}Wug4zAc?LMgHk=ׅgu;h&3Oj]ʢtvA{w5,'/,Ro?M4_Z?U,Y
Ŷ-l"Y]t/Yp33<\ߛ팳-
OR_Z_OS`-?Mbd!n?R7$bFVlx΢[oޏ
5(ef>=O=Ֆz)Ee?G{IOK46Uaik'#P
]ny@tqc*Uv~Bgvmۍ<OE=
[?O=T?M4_Z}b=o^>E'YF(5̋kMUls>gt_rkv_Ms׿^{IOE46oVծUmXYc5ͪ1{k׵ȝ?nFOYCJ۽FwTr>=f/k*geS32L?:V
]zu\.ҽvutpj譸R|R;z[oM;h+{-ѕ?E蹝k05Cq0?KCH{ՎV o>e1??ebϦ>g{E?ʳ󿲬.c[H[>+e\v]	>LH٭Pۋ	4ndf1*,؝jv551d.MeYߜTmm\",KZyy5}}ǧݕKKTyx[ dRξwmzg'=3ѧ`WI7
7Ɓ%?AjIKrH z~iu|@/B9:ˬ9uT936VzmbfP,WuC.nMn[}VSg;)V6CZm~*_S!8Hmw~Cw5!DF'{Vd+}J4fcq݊X涧Y5{ޥ;gu';Ϧ˘ǜx.oI++.Գӱ.k+%89!uy[^Fs[{v8meIK2ȈTđz
~3zt1~E=[[[}lįY_sհp}eYLw{,~ϫ]9-7_[R#0DdxO	?t
>eG1\4io_RY>e$C׾΍־껧c69UNc5{X[kc:y1F[;? |H;ar560٠hQ|񱕆e==
tzq7?cG#|ٸ%!s;E5Rrwߑ_U׊˷>ә/;k.wa +wu7i*hݺߛ?V7(edxzߨ/xO]#_YG7ݵaU×TU}^;vKΜSoXAfexR.kK@ݻmww`um6񕗐IucLskg2Id[(R~ъŏ>n'SVkc=eggf?Z]7OW>׿&p]^m`ȭme
N.)Q>)g]f}b4y?c*2m`^
W=,Ժ̸©۽ x~f(DiK҈F	  };ͦټ#fszWQꁔgUXpuQ]ev7*9*Nn-`caH~mo2~[JzQŠd3k۽2~o}Nϫ]zz|~4nI2X&w8+H|[~}aIfW`f=ګimXVW3ӛӳv_7$LOOu[:}e85Y/`Y{?u-\RHh_p	G+%R츁2K^?qƾkI!]osi^?qƾkI?J^?qƗsk洒Ssi^?qƾkI%?J^?qƗsk洒Ssk7?jVhuY
i~c.ƍۊʫg%I)8BIM'File written by Adobe Photoshop 4.0Adobed@
				




2s	
	
s!1AQa"q2B#R3b$r%C4Scs5D'6Tdt&	
EFVU(eufv7GWgw8HXhx)9IYiy*:JZjzm!1AQa"q2#BRbr3$4CS%cs5DT	
&6E'dtU7()󄔤euFVfvGWgw8HXhx9IYiy*:JZjz?7={Zԯ|\^\O4XBI$	fvbYXqW~o~`*~ZjCA<+.h`Qurmc#VG_Tˡ<"{[V㳻@wB}l#Z[K,44u_/5X)e4k[[lO)*VHn(T":]G__~.|y5-?=Lc8ʣ.kC {_TT2ʉiOiCwTT1WʉiOiCwTT1WʉiOiCwTT1WʉiOiCwTT1Wʧ?_V^[}{=.>=:p{OS_yAyF\'m
cZjZlS&c[J0({Eƞ_W_y95J,YkҨ`:fHQsv$6x+:>x寛jU/}X	 
2ۏ_rTڟ??uv{^w氵Akw+
Z’	cc~ʪ/9{|j/*Z.դsDGy-VagUd_moo}}K^jSy4"	4JC3s h^iy~EdVϓnV-Vt3F_q4К)=̑,#'ʿYtsPIIyk||s{Ci,[xig(!_ͺGɟI4?OѼ;>S5ĶBdЦTqBj$`E7+nU}es-_SNV=orDM+5L$v>rK8qW\ΫM.<]V7t
qY?6gq-hNy?v}=c^ZJ"JG9ϰh8X%],n?-+7lٜAȍhskIaqKStqZr[
=
/u)L84wMs<ڂ6O"hVZ-BkG=1*<Q"n\3jW>FX
:>O~fuhp7<'~H>yMkGKK$qv.\Do>#^8gO^㫱ו.ފ_Mǖ}>I4k
*][C"j"jqRM˺+6_ .yn!*եs/Xo袎Qc5	h1W\ΫvC^KmD0h&72^[7Z*5!96-jZ5xmcuvmPQ@N{1s垢t9tr7.}_KGShTuQ-C,9CjOÿ՜ߑI"9AM[1'a1!VjOLi$Lwuz[yrZ/8xg`f9DqF]e.W'BP??'jW.lDZ--"]F@
èr-#DN3vqq_KI'>vgo..<.Q@<ʱ4dQ_ň@.~Yk敱^[蜁t9uHBv<{#zXK%qovw]/?/Ug?k{+4~>N?-}<w?#OWMƧ7C
"I$
ϢI
Crzuk;Gvf$K
j[G$PMJ-Esk
txy.P|ݗ|r~Oߐ~֣]/Q"EO?=>N-n/OH#Iikn
PQNc7<S-vlzhnD;ү,_DGUnĩ\-WyRE'n}؜˖&da襧LJ8<5~/.ZǖtCQ뾵ݍ^O$lƊEOA>冦B3r'&M%(FDnb	cɣϱtb$ȡ)j  ⯝;4o4jwl"ƹp[e?%I&OhF{D	
"ȿ%]
W3EJEǯ}ؑ')?*kyz(Pf6>Й}᠈Ip錄%
4O&kPyGTy$IP2Ah}e?e*/UXrVLFɳDPSe
6YY|䳻OtYIrsf;OR?ѝ1[B;R:S9~W#Sɖ_t46"IYS1>&8@kQX^,n4%-GP-ܷZgq{w1 eA2SK	D'^]򗖼o%44oRZ+ԞRw;v9N\nfܜlXcXyK˺^auuEo9iV0tg O<lp,}G5kK-FT5Vo9H$
 ,/ʸPE8]^*ٰ=?c(}o"y_VM{*y{L]?Go7ՏyP-J*Q;]?)ኲʬUX*WUbܪ]UrwV*ʬUX*WUbܪ^MwWc_Zope-2.9.4-retire_zpkg/lib/python/App/www/chooseDatabase.pt0000644000175000017500000000113710050234363023575 0ustar  tseavertseaver





Databases








Main








Zope-2.9.4-retire_zpkg/lib/python/App/www/transparent_bar.gif0000644000175000017500000000010410050234363024170 0ustar  tseavertseaverGIF89a!Created with The GIMP!
,L;Zope-2.9.4-retire_zpkg/lib/python/App/www/permission.gif0000755000175000017500000000160610050234363023206 0ustar  tseavertseaverGIF89aPPP@@@@@!,cT0†2(D)Fxǎ @$H|H@H(ٲK4i G3yTp$͚C}Mqypdx\egc[	
}!1AQa"q2#BR$3br	
%&'()*456789:CDEFGHIJSTUVWXYZcdefghijstuvwxyz?~Q=)T=JQzta`dgKqx'g=8RW$r>z@FF	=Gz6rs=S+q?zn6sCK7mZh?1#tTCr=kуtk
}QEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEفoO^NXs~nN C
k
}QEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEr*sǯց26Nz}Nh r?cc
{qqs~@=AgR'=qc~8n-s/9+ӟ)W3
$`gN[\R7=H?˵uO(((((((((((((((((((((((((((((((((`$GxlqQv=sMf'9>q&0OnڀFp	
i9F}=~c=)uP0QN8>T*
G^r';q~Tdcc~QEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQYwsA,C=GQOdp=3o'<`aNI\H=xw<2&רNNFAN(rP	)0qgN >4=-eqMunκEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEgK9#*}I0G#=@F2zE'yU#whR#J3\{aCmW9J2Cc B#'&@,H8w=pe*	mîzF?tE:(((((((((((((((((((((((((((((((((*?41PIʅ6BT$s^E0H duԞ ~T1F!F#֞xaΘ	ҹ""m?	ylzF~QEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQEQ_Zope-2.9.4-retire_zpkg/lib/python/App/www/dbManage.gif0000644000175000017500000000155510050234363022514 0ustar  tseavertseaverGIF89aPPP@@@@@!,JHA*Lx"(0ʼn+ZQ`;"$p!IALq%H(_J)eM/ETٰ$C;Zope-2.9.4-retire_zpkg/lib/python/App/www/load_bar.gif0000644000175000017500000000010410050234363022546 0ustar  tseavertseaverGIF89a!Created with The GIMP!
,D;Zope-2.9.4-retire_zpkg/lib/python/App/www/help.jpg0000755000175000017500000000535010050234363021761 0ustar  tseavertseaverJFIFHHzPhotoshop 3.08BIMxHH@[ (hht@h0@CN' dVe9CV+SR8BIMHH8BIM8BIM
8BIM'
8BIMH/fflff/ff2Z5-8BIMp8BIM8BIM8BIM@@8BIM	M1JFIFHH'File written by Adobe Photoshop 4.0Adobed			



"?	
	
3!1AQa"q2B#$Rb34rC%Scs5&DTdE£t6UeuF'Vfv7GWgw5!1AQaq"2B#R3$brCScs4%&5DTdEU6teuFVfv'7GWgw?I]URSMn}i$tKNxZoRו +*Y7Bg?>
8r_'E[7)pl<\5߃*Ją\Tu%RSES]".,^U]F.+[-NbeɪyGnz~/*d;Td*$,ITtooK[/oKƒ]Wpע9]?ʲ:Vn,\wS^1[ˇI%zqWJٷp޷jNs}<\WֶDp֗nnAPIOTTd-견OᮗC]fk4RZKU~SZ]ҪMZANDE4	\US[m_ѻVGRZ+[
^So_~2Ŷ.giE]^ILz$eI^PINj@RIO{_V|yj|:`WXZ*~oU_[݊yxJ򺀄1=*2GIM5aQZ)Ө%q%5.+pKݗ8ZG\J/f'YDSTDUBUIOLIN}ukqxlˊ|7>Ntu7]?Ml*&ڌՅ *ҒJs8BIM'File written by Adobe Photoshop 4.0Adobed		





	
	
s!1AQa"q2B#R3b$r%C4Scs5D'6Tdt&	
EFVU(eufv7GWgw8HXhx)9IYiy*:JZjzm!1AQa"q2#BRbr3$4CS%cs5DT	
&6E'dtU7()󄔤euFVfvGWgw8HXhx9IYiy*:JZjz?~v_+PѼeԦIq`uo9"wg>&_[2.B9>ҙeW3mZ}'9)=qc8yИ}6z⼹-RFp2~k-wvQ\2_"hCFCI/)K8VM]'oZope-2.9.4-retire_zpkg/lib/python/App/www/PythonPoweredSmall.gif0000755000175000017500000000055110050234363024614 0ustar  tseavertseaverGIF89a7ֽBBB999111)))c!
,7I+u8덭č$sǣ>ˮoܪts@@cp8&*&́B);\aiC9,Xp~:oqpl#"w`7{}~`pKJNd
#P.0>qY-$PgtKNs.%/S9m6,087d29%bC_y{Fa,|riBH̛H|lVna]Rov,I
R=!!cF֬bE,	J(,iK`.6zCJ@RK-_6;Zope-2.9.4-retire_zpkg/lib/python/App/www/arrow.jpg0000755000175000017500000000477710050234363022177 0ustar  tseavertseaverJFIFHHPhotoshop 3.08BIMxHH@[ (hht@h0@CN' dVe9CV+SR8BIMHH8BIM8BIM
8BIM'
8BIMH/fflff/ff2Z5-8BIMp8BIM8BIM8BIM@@8BIM	JFIFHH'File written by Adobe Photoshop 4.0Adobed			



"?	
	
3!1AQa"q2B#$Rb34rC%Scs5&DTdE£t6UeuF'Vfv7GWgw5!1AQaq"2B#R3$brCScs4%&5DTdEU6teuFVfv'7GWgw?$U<8+K/^>.!j'	[ַoZiiUU}RIMqVFIM$L*	)JEs~ջȟIu]2f쭵MAMUzz.J
%kֺSCUSARZJJEW(O~ԋMd(HoD:\YT'[ItK
g)O	rzF\RHt)tS5e'F+_EѕdunD-傆tMYoz(!iW>DհT^NU.I%f^C~|41-rMjpB~_Zope-2.9.4-retire_zpkg/lib/python/App/www/factory.gif0000644000175000017500000000155310050234363022463 0ustar  tseavertseaverGIF89aPPP@@@@@!,H@`	(,Р6D.th`"Ǝ99"ȑR\R ˗*]|)sfK6Y@@;Zope-2.9.4-retire_zpkg/lib/python/App/www/CacheManager_icon.gif0000644000175000017500000000157710050234363024330 0ustar  tseavertseaverGIF89aPPP@@@@@!,@\@`@!0aċ+:p@ƅDFJZDBz1Kmĩ$Ǟ<]d	Еk*S;Zope-2.9.4-retire_zpkg/lib/python/App/www/cpSystem.gif0000644000175000017500000000162010050234363022616 0ustar  tseavertseaverGIF89aPPP@@@@@!,@m@
 0eI^\JlZ2bz=^.s_lx+w_	uaL|$IJI$RI$V2J}
keѤd\R4xurpqwt	$^1L٪W^S)/FY))]Ұ=D^$ʢL+JuVZQi-d$CVS%5T֊2JsQ8BIM'File written by Adobe Photoshop 4.0Adobed		





	
	
s!1AQa"q2B#R3b$r%C4Scs5D'6Tdt&	
EFVU(eufv7GWgw8HXhx)9IYiy*:JZjzm!1AQa"q2#BRbr3$4CS%cs5DT	
&6E'dtU7()󄔤euFVfvGWgw8HXhx9IYiy*:JZjz?Pk_.ko6MtIiWi$QK$+^,Cc1I~'TOTa>Nqg O$,QOI3{[>៉)Z֏_C5H.}&݀k̷&5y	>df	zK
g{y1[Y;$gb'Jݪ\f:_Zope-2.9.4-retire_zpkg/lib/python/App/www/zopelogo.jpg0000755000175000017500000000542610050234363022673 0ustar  tseavertseaverJFIF,,The Gimp is The WayCC Z"	
(	
!#$"!#"$?OJs/so8:-^E׫y5y2m
hQI2~_
G{P=Ӛ?9}KqF!@"}=i`S3鶱".SYU l;=iF{|S_PZS[読A&ǫ|G=K\?^;JLul_W.}[1sC`2 qwk齟[ܮhUV]~
ΆGݩLqgvNRB[Ͷ~KaiE)ZkA	N
ϵ	[QA(qp꣏ETQ`"Tk0'lX:٧tgR{o5VU`!]:bݰ^[w1H1|=PіB^v .oy'S
dvdaJg%cX;{uFcň,ZZoU>fE%PL12Y; Q|M[ABDr(NRfL|F9߰,]>IZB{9Et.}?d
g:eX7q7g 8,0O8H󻰮F-WbĂ@U!-rP5-Z21!2]fx4,\k!iYlC֒Z>jx
/;xرKw}mS50`c3t[|>?=k=CežHFEF%zֶ"wd#acܲ^[YUn>L$ZG?NKuvK{7iX&hodQЌƬkL-?a|:A2ؿѾr枡>WLMPU6iPEj-4Mؖ89^R&x7>bm}W4aSqKͮ?h~XUMƸzMqQyҺn.L*-\o-TtiįG$$]Q#̄񢰀nDJVӓd#1f['P#VNk2ϙ-_|.	5 njzdQg?Ǯ?||{iEȩ	KV;c&ߪy;9E9ZQiVC6ŤZAL1(~#ְs2\xE]j̴9u)}9t>3Bm^;,}Ʊp/?SWf	km]+՝
)ᦿTɃh"s5kYi9$Wuqd󕩦h`
Rڛ.ji7DG=|bxEѶ)SIsԺhIA&_cI5$Yot{E6wjC%K+ߺ1$rL{)Q:k?&G!g8lnLFu*689	#&۬)c=s0ucQ:%^**tSkDbW#A6mŐ!N%l,IמXjHz:Sג9:k*%[D['jk؆	T3=Dg@]
χhu]{FɹVN#.QRHL,ƜVh28|*qZ*k^L6!]sy*
NBʰQ+NyѽU`iׁkm0D&"zc}l0"M:
U`nf۩f89/Յ^lP~Gf<#d_81Zo'ط/HV8xhyNȶ}HQInKԽgΏiֻZope-2.9.4-retire_zpkg/lib/python/App/Undo.py0000644000175000017500000001166710337373524021002 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Undo support.

$Id: Undo.py 40222 2005-11-18 15:46:28Z andreasjung $
"""

from Acquisition import aq_base, aq_parent, aq_inner
from AccessControl import getSecurityManager
from DateTime import DateTime
import Globals, ExtensionClass
from ZopeUndo.Prefix import Prefix
import transaction
from zope.interface import implements

from interfaces import IUndoSupport


class UndoSupport(ExtensionClass.Base):

    implements(IUndoSupport)

    __ac_permissions__=(
        ('Undo changes', (
            'manage_undo_transactions',
            'undoable_transactions',
            'manage_UndoForm',
            )),
        )

    manage_options=(
        {'label':'Undo', 'action':'manage_UndoForm',
         'help':('OFSP','Undo.stx')},
        )

    manage_UndoForm=Globals.DTMLFile(
        'dtml/undo',
        globals(),
        PrincipiaUndoBatchSize=20,
        first_transaction=0,
        last_transaction=20
        )

    def get_request_var_or_attr(self, name, default):
        if hasattr(self, 'REQUEST'):
            REQUEST=self.REQUEST
            if REQUEST.has_key(name): return REQUEST[name]
            if hasattr(self, name): v=getattr(self, name)
            else: v=default
            REQUEST[name]=v
            return v
        else:
            if hasattr(self, name): v=getattr(self, name)
            else: v=default
            return v

    def undoable_transactions(self, first_transaction=None,
                              last_transaction=None,
                              PrincipiaUndoBatchSize=None):

        if first_transaction is None:
            first_transaction=self.get_request_var_or_attr(
                'first_transaction', 0)

        if PrincipiaUndoBatchSize is None:
            PrincipiaUndoBatchSize=self.get_request_var_or_attr(
                'PrincipiaUndoBatchSize', 20)

        if last_transaction is None:
            last_transaction=self.get_request_var_or_attr(
                'last_transaction',
                first_transaction+PrincipiaUndoBatchSize)

        spec={}

        # A user is allowed to undo transactions that were initiated
        # by any member of a user folder in the place where the user
        # is defined.
        user = getSecurityManager().getUser()
        if hasattr(user, 'aq_parent'):
            path = '/'.join(user.aq_parent.getPhysicalPath()[1:-1])
        else:
            path=''
        if path: spec['user_name']=Prefix(path)

        if getattr(aq_parent(aq_inner(self)), '_p_jar', None) == self._p_jar:
            # We only want to undo things done here (and not in mounted
            # databases)
            opath='/'.join(self.getPhysicalPath())
        else:
            # Special case: at the root of a database,
            # allow undo of any path.
            opath = None
        if opath: spec['description']=Prefix(opath)

        r = self._p_jar.db().undoInfo(
            first_transaction, last_transaction, spec)

        for d in r:
            d['time']=t=DateTime(d['time'])
            desc = d['description']
            tid=d['id']
            if desc:
                desc = desc.split()
                d1=desc[0]
                desc = ''.join(desc[1:])
                if len(desc) > 60: desc = desc[:56]+' ...'
                tid = "%s %s %s %s" % (encode64(tid), t, d1, desc)
            else:
                tid = "%s %s" % (encode64(tid), t)
            d['id']=tid


        return r

    def manage_undo_transactions(self, transaction_info=(), REQUEST=None):
        """
        """
        undo=self._p_jar.db().undo

        for tid in transaction_info:
            tid=tid.split()
            if tid:
                transaction.get().note("Undo %s" % ''.join(tid[1:]))
                tid=decode64(tid[0])
                undo(tid)

        if REQUEST is None: return
        REQUEST['RESPONSE'].redirect("%s/manage_UndoForm" % REQUEST['URL1'])
        return ''

Globals.default__class_init__(UndoSupport)

########################################################################
# Blech, need this cause binascii.b2a_base64 is too pickly

import binascii

def encode64(s, b2a=binascii.b2a_base64):
    if len(s) < 58: return b2a(s)
    r=[]; a=r.append
    for i in range(0, len(s), 57):
        a(b2a(s[i:i+57])[:-1])
    return ''.join(r)

def decode64(s, a2b=binascii.a2b_base64):
    __traceback_info__=len(s), `s`
    return a2b(s+'\n')

del binascii
Zope-2.9.4-retire_zpkg/lib/python/App/RefreshFuncs.py0000644000175000017500000002351410337373524022464 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
'''
Functions for refreshing products.
$Id: RefreshFuncs.py 40222 2005-11-18 15:46:28Z andreasjung $
'''

import os, sys
from time import time
import transaction
import Products
from ExtensionClass import Base
from Globals import PersistentMapping
from zLOG import format_exception, LOG, ERROR, INFO

global_classes_timestamp = 0
products_mod_times = {}

_marker = []  # create a new marker object.

refresh_exc_info = {}

class dummyClass: pass
class dummyClass2 (Base): pass
def dummyFunc(): pass

ClassTypes = (type(dummyClass), type(dummyClass2))
ModuleType = type(sys)
FuncType = type(dummyFunc)

next_auto_refresh_check = 0
AUTO_REFRESH_INTERVAL = 2  # 2 seconds.

# Functions for storing and retrieving the auto-refresh state for
# each product.

def _getCentralRefreshData(jar, create=0):
    root = jar.root()
    if root.has_key('RefreshData'):
        rd = root['RefreshData']
    else:
        rd = PersistentMapping()
        if create:
            root['RefreshData'] = rd
    return rd

def isAutoRefreshEnabled(jar, productid):
    rd = _getCentralRefreshData(jar)
    ids = rd.get('auto', None)
    if ids:
        return ids.get(productid, 0)
    else:
        return 0

def enableAutoRefresh(jar, productid, enable):
    productid = str(productid)
    rd = _getCentralRefreshData(jar, 1)
    ids = rd.get('auto', None)
    if ids is None:
        if enable:
            rd['auto'] = ids = PersistentMapping()
        else:
            return
    if enable:
        ids[productid] = 1
    else:
        if ids.has_key(productid):
            del ids[productid]

def listAutoRefreshableProducts(jar):
    rd = _getCentralRefreshData(jar)
    auto = rd.get('auto', None)
    if auto:
        ids = []
        for k, v in auto.items():
            if v:
                ids.append(k)
        return ids
    else:
        return ()

def getDependentProducts(jar, productid):
    rd = _getCentralRefreshData(jar)
    products = rd.get('products', None)
    if products is None:
        return ()
    product = products.get(productid, None)
    if product is None:
        return ()
    return product.get('dependent_products', ())

def setDependentProducts(jar, productid, dep_ids):
    productid = str(productid)
    rd = _getCentralRefreshData(jar, 1)
    products = rd.get('products', None)
    if products is None:
        rd['products'] = products = PersistentMapping()
    product = products.get(productid, None)
    if product is None:
        products[productid] = product = PersistentMapping()
    product['dependent_products'] = tuple(map(str, dep_ids))


# Functions for performing refresh.

def getReloadVar(module):
    reload_var = getattr(module, '__refresh_module__', _marker)
    if reload_var is _marker:
        reload_var = getattr(module, '__reload_module__', _marker)
    if reload_var is _marker:
        reload_var = 1
    return reload_var

def listRefreshableModules(productid):
    prefix = "Products.%s" % productid
    prefixdot = prefix + '.'
    lpdot = len(prefixdot)
    rval = []
    for name, module in sys.modules.items():
        if module and (name == prefix or name[:lpdot] == prefixdot):
            reload_var = getReloadVar(module)
            if reload_var:
                rval.append((name, module))
    return rval

def logBadRefresh(productid):
    exc = sys.exc_info()
    try:
        LOG('Refresh', ERROR, 'Exception while refreshing %s'
            % productid, error=exc)
        if hasattr(exc[0], '__name__'):
            error_type = exc[0].__name__
        else:
            error_type = str(exc[0])
        error_value = str(exc[1])
        info = ''.join(format_exception(exc[0], exc[1], exc[2], limit=200))
        refresh_exc_info[productid] = (error_type, error_value, info)
    finally:
        exc = None

def performRefresh(jar, productid):
    '''Attempts to perform a refresh operation.
    '''
    refresh_exc_info[productid] = None
    setupModTimes(productid)  # Refresh again only if changed again.

    modlist = listRefreshableModules(productid)
    former_modules = {}
    try:
        # Remove modules from sys.modules but keep a handle
        # on the old modules in case there's a problem.
        for name, module in modlist:
            m = sys.modules.get(name, None)
            if m is not None:
                former_modules[name] = m
                del sys.modules[name]

        # Reimport and reinstall the product.
        from OFS import Application
        Application.reimport_product(productid)
        app = jar.root()['Application']
        Application.reinstall_product(app, productid)
        return 1
    except:
        # Couldn't refresh.  Reinstate removed modules.
        for name, module in former_modules.items():
            sys.modules[name] = module
        raise

def performSafeRefresh(jar, productid):
    try:
        LOG('Refresh', INFO, 'Refreshing product %s' % productid)
        if not performRefresh(jar, productid):
            return 0
    except:
        logBadRefresh(productid)
        return 0
    else:
        return 1

def performFullRefresh(jar, productid):
    # Refresh dependent products also.
    if performSafeRefresh(jar, productid):
        dep_ids = getDependentProducts(jar, productid)
        for dep_id in dep_ids:
            if isAutoRefreshEnabled(jar, dep_id):
                if not performSafeRefresh(jar, dep_id):
                    return 0
    else:
        return 0
    return 1

def getLastRefreshException(productid):
    return refresh_exc_info.get(productid, None)

# Functions for quickly scanning the dates of product modules.

def tryFindProductDirectory(productid):
    path_join = os.path.join
    isdir = os.path.isdir
    exists = os.path.exists

    for products_dir in Products.__path__:
        product_dir = path_join(products_dir, productid)
        if not isdir(product_dir): continue
        if not exists(path_join(product_dir, '__init__.py')):
            if not exists(path_join(product_dir, '__init__.pyc')):
                continue
        return product_dir
    return None

def tryFindModuleFilename(product_dir, filename):
    # Try different variations of the filename of a module.
    path_join = os.path.join
    isdir = os.path.isdir
    exists = os.path.exists

    found = None
    fn = path_join(product_dir, filename + '.py')
    if exists(fn):
        found = fn
    if not found:
        fn = fn + 'c'
        if exists(fn):
            found = fn
    if not found:
        fn = path_join(product_dir, filename)
        if isdir(fn):
            fn = path_join(fn, '__init__.py')
            if exists(fn):
                found = fn
            else:
                fn = fn + 'c'
                if exists(fn):
                    found = fn
    return found

def setupModTimes(productid):
    mod_times = []
    product_dir = tryFindProductDirectory(productid)
    if product_dir is not None:
        modlist = listRefreshableModules(productid)

        path_join = os.path.join
        exists = os.path.exists

        for name, module in modlist:
            splitname = name.split( '.')[2:]
            if not splitname:
                filename = '__init__'
            else:
                filename = apply(path_join, splitname)
            found = tryFindModuleFilename(product_dir, filename)

            if found:
                try: mtime = os.stat(found)[8]
                except: mtime = 0
                mod_times.append((found, mtime))
    products_mod_times[productid] = mod_times

def checkModTimes(productid):
    # Returns 1 if there were changes.
    mod_times = products_mod_times.get(productid, None)
    if mod_times is None:
        # Initialize the mod times.
        setupModTimes(productid)
        return 0
    for filename, mod_time in mod_times:
        try: mtime = os.stat(filename)[8]
        except: mtime = 0
        if mtime != mod_time:
            # Something changed!
            return 1
    return 0

# Functions for performing auto-refresh.

def checkAutoRefresh(jar):
    '''
    Returns the IDs of products that need to be auto-refreshed.
    '''
    # Note: this function is NOT allowed to change the database!
    global next_auto_refresh_check
    now = time()
    if next_auto_refresh_check and next_auto_refresh_check > now:
        # Not enough time has passed.
        return ()
    next_auto_refresh_check = now + AUTO_REFRESH_INTERVAL

    rd = _getCentralRefreshData(jar)
    ids = rd.get('auto', None)
    if not ids:
        return ()
    auto_refresh_ids = []
    for productid in ids.keys():
        if checkModTimes(productid):
            auto_refresh_ids.append(productid)
    return auto_refresh_ids

def finishAutoRefresh(jar, productids):
    # This function is allowed to change the database.
    for productid in productids:
        performFullRefresh(jar, productid)

def autoRefresh(jar):
    # Must be called before there are any changes made
    # by the connection to the database!
    auto_refresh_ids = checkAutoRefresh(jar)
    if auto_refresh_ids:
        finishAutoRefresh(jar, auto_refresh_ids)
        from ZODB import Connection
        Connection.resetCaches()
        transaction.commit()
        jar._resetCache()
        transaction.begin()

def setupAutoRefresh(jar):
    # Install hook.
    from App.ZApplication import connection_open_hooks
    connection_open_hooks.append(autoRefresh)
    # Init mod times.
    checkAutoRefresh(jar)
Zope-2.9.4-retire_zpkg/lib/python/App/Permission.py0000644000175000017500000000704310337373524022216 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
__doc__='''Zope registerable permissions

$Id: Permission.py 40222 2005-11-18 15:46:28Z andreasjung $'''
__version__='$Revision: 1.9 $'[11:-2]

import OFS.SimpleItem, Acquisition, Globals, ExtensionClass, AccessControl.Role
from AccessControl import ClassSecurityInfo, Permissions

view_management_screens = Permissions.view_management_screens
define_permissions = Permissions.define_permissions


class Permission(
    AccessControl.Role.RoleManager,
    Globals.Persistent, Acquisition.Implicit, OFS.SimpleItem.Item
    ):
    "Model Permission meta-data"
    meta_type='Zope Permission'
    icon='p_/Permission_icon'
    security = ClassSecurityInfo()

    manage_options=(
        (
        {'label':'Edit', 'action':'manage_main',
         'help':('OFSP','Zope-Permission_Edit.stx')},
        )
        +AccessControl.Role.RoleManager.manage_options
        +OFS.SimpleItem.Item.manage_options
        )

    def __init__(self, id, title, name):
        self.id=id
        self.title=title
        self.name=name

    security.declareProtected(define_permissions, 'manage_edit')
    def manage_edit(self, title, name, REQUEST=None):
        "Modify Permission properties."
        if title != self.title: self.title=title
        if name != self.name:
            self._unregister()
            self.name=name
            self._register()
        if REQUEST is not None: return self.manage_main(self, REQUEST)

    security.declarePrivate('manage_afterAdd')
    def manage_afterAdd(self, item, container):
        self._register()

    security.declarePrivate('manage_beforeDelete')
    def manage_beforeDelete(self, item, container):
        self._unregister()

    def _register(self):
        # Register with the product folder
        product=self.aq_parent
        product.aq_acquire('_manage_add_product_permission')(
            product, self.name)

    def _unregister(self):
        # Unregister with the product folder
        product=self.aq_parent
        product.aq_acquire('_manage_remove_product_permission')(
            product, self.name)

    security.declareProtected(view_management_screens, 'manage_main')
    manage_main=Globals.DTMLFile('dtml/editPermission',globals())

    index_html=None

Globals.InitializeClass(Permission)


class PermissionManager(ExtensionClass.Base):

    security = ClassSecurityInfo()

    meta_types={
        'name': Permission.meta_type, 'action': 'manage_addPermissionForm'
        },

    security.declareProtected(define_permissions, 'manage_addPermissionForm')
    manage_addPermissionForm=Globals.DTMLFile('dtml/addPermission',globals())

    security.declareProtected(define_permissions, 'manage_addPermission')
    def manage_addPermission(
        self, id, title, permission, REQUEST=None):
        ' '
        i=Permission(id, title, permission)
        self._setObject(id,i)
        if REQUEST is not None:
            return self.manage_main(self,REQUEST,update_menu=1)

Globals.InitializeClass(PermissionManager)
Zope-2.9.4-retire_zpkg/lib/python/App/Common.py0000755000175000017500000001140610337373524021317 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

"""Commonly used utility functions."""

__version__='$Revision: 1.20 $'[11:-2]

import os
import sys
import time

# Legacy API for this module; 3rd party code may use this.
from os.path import realpath


# These are needed because the various date formats below must
# be in english per the RFCs. That means we can't use strftime,
# which is affected by different locale settings.
weekday_abbr = ['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']
weekday_full = ['Monday', 'Tuesday', 'Wednesday', 'Thursday',
                'Friday', 'Saturday', 'Sunday']
monthname    = [None, 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
                'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']


def iso8601_date(ts=None):
    # Return an ISO 8601 formatted date string, required
    # for certain DAV properties.
    # '2000-11-10T16:21:09-08:00
    if ts is None: ts=time.time()
    return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(ts))

def rfc850_date(ts=None):
    # Return an HTTP-date formatted date string.
    # 'Friday, 10-Nov-00 16:21:09 GMT'
    if ts is None: ts=time.time()
    year, month, day, hh, mm, ss, wd, y, z = time.gmtime(ts)
    return "%s, %02d-%3s-%2s %02d:%02d:%02d GMT" % (
            weekday_full[wd],
            day, monthname[month],
            str(year)[2:],
            hh, mm, ss)

def rfc1123_date(ts=None):
    # Return an RFC 1123 format date string, required for
    # use in HTTP Date headers per the HTTP 1.1 spec.
    # 'Fri, 10 Nov 2000 16:21:09 GMT'
    if ts is None: ts=time.time()
    year, month, day, hh, mm, ss, wd, y, z = time.gmtime(ts)
    return "%s, %02d %3s %4d %02d:%02d:%02d GMT" % (weekday_abbr[wd],
                                                    day, monthname[month],
                                                    year,
                                                    hh, mm, ss)

def absattr(attr, callable=callable):
    # Return the absolute value of an attribute,
    # calling the attr if it is callable.
    if callable(attr):
        return attr()
    return attr

def aq_base(ob, getattr=getattr):
    # Return the aq_base of an object.
    return getattr(ob, 'aq_base', ob)

def is_acquired(ob, hasattr=hasattr, aq_base=aq_base, absattr=absattr):
    # Return true if this object is not considered to be
    # a direct subobject of its acquisition parent
    # Used to prevent acquisition side-affects in FTP traversal
    # Note that this method is misnamed since parents can (and do)
    # spoof it. It is not a true measure of whether something is
    # acquired, it relies on the parent's parent-ness exclusively
    if not hasattr(ob, 'aq_parent'):
        # We can't be acquired if we don't have an aq_parent
        return 0

    parent = aq_base(ob.aq_parent)
    absId  = absattr(ob.id)

    if hasattr(parent, absId):
        # Consider direct attributes not acquired
        return 0

    if hasattr(parent, '__getitem__'):
        # Use __getitem__ as opposed to has_key to avoid TTW namespace
        # issues, and to support the most minimal mapping objects
        try:
            # We assume that getitem will not acquire which
            # is the standard behavior for Zope objects
            if aq_base(ob.aq_parent[absId]) is aq_base(ob):
                # This object is an item of the aq_parent, its not acquired
                return 0
        except KeyError:
            pass

    if hasattr(parent,'_objects'):
        # XXX This is really icky
        # This ugly mess is for ZClass methods I think
        if absId+' ' in parent.objectIds():
            return 0

    if hasattr(aq_base(ob), 'isTopLevelPrincipiaApplicationObject') and \
            ob.isTopLevelPrincipiaApplicationObject:
        # This object the top level
        return 0
    return 1 # This object is acquired by our measure


def package_home(globals_dict):
    __name__=globals_dict['__name__']
    m=sys.modules[__name__]
    if hasattr(m,'__path__'):
        r=m.__path__[0]
    elif "." in __name__:
        r=sys.modules[__name__[:__name__.rfind('.')]].__path__[0]
    else:
        r=__name__
    return os.path.abspath(r)


# We really only want the 3-argument version of getattr:
attrget = getattr

def Dictionary(**kw): return kw # Sorry Guido
Zope-2.9.4-retire_zpkg/lib/python/App/class_init.py0000644000175000017500000000667710340205654022222 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

import logging
from AccessControl.PermissionRole import PermissionRole
import AccessControl.Permission

class ApplicationDefaultPermissions:
    _View_Permission='Manager', 'Anonymous'
    _Access_contents_information_Permission='Manager', 'Anonymous'


def default__class_init__(self):
    dict=self.__dict__
    have=dict.has_key
    ft=type(default__class_init__)
    dict_items=dict.items()

    for name, v in dict_items:
        if getattr(v, '_need__name__', 0):
            d = v.__dict__
            oldname = d.get('__name__', '')
            if d.get('_implicit__name__', 0):
                # Already supplied a name.
                if name != oldname:
                    # Tried to implicitly assign a different name!
                    try: classname = '%s.%s' % (
                        self.__module__, self.__name__)
                    except AttributeError: classname = `self`
                    logging.getLogger("Init").warning(
                        'Ambiguous name for method of %s: %r != %r',
                        classname, d['__name__'], name)
            else:
                # Supply a name implicitly so that the method can
                # find the security assertions on its container.
                v._implicit__name__ = 1
                v.__name__ = name
            if name=='manage' or name[:7]=='manage_':
                name=name+'__roles__'
                if not have(name):
                    setattr(self, name, ('Manager',))
        elif name=='manage' or name[:7]=='manage_' and type(v) is ft:
            name=name+'__roles__'
            if not have(name):
                setattr(self, name, ('Manager',))
                
    # Look for a SecurityInfo object on the class. If found, call its
    # apply() method to generate __ac_permissions__ for the class. We
    # delete the SecurityInfo from the class dict after it has been
    # applied out of paranoia.
    for key, value in dict_items:
        if hasattr(value, '__security_info__'):
            security_info=value
            security_info.apply(self)
            delattr(self, key)
            break

    if self.__dict__.has_key('__ac_permissions__'):
        AccessControl.Permission.registerPermissions(self.__ac_permissions__)
        for acp in self.__ac_permissions__:
            pname, mnames = acp[:2]
            if len(acp) > 2:
                roles = acp[2]
                pr = PermissionRole(pname, roles)
            else:
                pr=PermissionRole(pname)
            for mname in mnames:
                setattr(self, mname+'__roles__', pr)
                if mname and not hasattr(self, mname):
                    logging.getLogger("Init").warning(
                        "Class %s.%s has a security declaration for "
                        "nonexistent method %r", self.__module__,
                        self.__name__, mname)
Zope-2.9.4-retire_zpkg/lib/python/App/Hotfixes.py0000644000175000017500000000365410337373524021663 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

from version_txt import getZopeVersion
from zLOG import LOG, INFO, WARNING

merged_hotfixes = {
    'Hotfix_2001-09-28': 1,
    'Hotfix_2002-03-01': 1,
    'Hotfix_2002-04-15': 1,
    'Hotfix_2002-06-14': 1,
    }


APPLY = 1
ALREADY_MERGED = 0
OUTDATED_ZOPE = None


def isMerged(name):
    return merged_hotfixes.get(name, 0)


def logHotfix(id, apply_hotfix):
    if apply_hotfix:
        LOG('Hotfixes', INFO, 'Applying %s' % id)
    elif apply_hotfix is OUTDATED_ZOPE:
        LOG('Hotfixes', WARNING, 'Not applying %s.  It is not designed for '
            'this version of Zope.  Please uninstall the hotfix product.'
            % id)
    else:  # ALREADY_MERGED
        LOG('Hotfixes', WARNING, 'Not applying %s.  The fix has already been '
            'merged into Zope.  Please uninstall the hotfix product.'
            % id)


def beforeApplyHotfix(id, req_major, req_minor, req_micro):
    major, minor, micro = getZopeVersion()[:3]
    if major > 0 and (
        (major * 10000 + minor * 100 + micro) <
        (req_major * 10000 + req_minor * 100 + req_micro)):
        # The version of Zope is too old for this hotfix.
        apply_hotfix = OUTDATED_ZOPE
    elif isMerged(id):
        apply_hotfix = ALREADY_MERGED
    else:
        apply_hotfix = APPLY
    logHotfix(id, apply_hotfix)
    return apply_hotfix
Zope-2.9.4-retire_zpkg/lib/python/App/ApplicationManager.py0000644000175000017500000004041210337373524023621 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
__doc__="""System management components"""

__version__='$Revision: 1.94 $'[11:-2]

import sys,os,time,Globals, Acquisition, os, Undo
from Globals import DTMLFile
from OFS.ObjectManager import ObjectManager
from OFS.Folder import Folder
from CacheManager import CacheManager
from DavLockManager import DavLockManager
from DateTime.DateTime import DateTime
from OFS import SimpleItem
from App.config import getConfiguration
from App.Dialogs import MessageDialog
from Product import ProductFolder
from version_txt import version_txt
from cStringIO import StringIO
from AccessControl import getSecurityManager
from zExceptions import Redirect
from Products.PageTemplates.PageTemplateFile import PageTemplateFile
from cgi import escape
import zLOG
import Lifetime

try: import thread
except: get_ident=lambda: 0
else: get_ident=thread.get_ident

class Fake:
    def locked_in_version(self): return 0

class DatabaseManager(Fake, SimpleItem.Item, Acquisition.Implicit):
    """Database management (legacy) """
    manage=manage_main=DTMLFile('dtml/dbMain', globals())
    manage_main._setName('manage_main')
    id        ='DatabaseManagement'
    name=title='Database Management'
    meta_type ='Database Management'
    icon='p_/DatabaseManagement_icon'

    manage_options=(
        (
        {'label':'Database', 'action':'manage_main',
         'help':('OFSP','Database-Management_Database.stx')},
        {'label':'Activity', 'action':'manage_activity',
         'help':('OFSP','Database-Management_Activity.stx')},
        {'label':'Cache Parameters', 'action':'manage_cacheParameters',
         'help':('OFSP','Database-Management_Cache-Parameters.stx')},
        {'label':'Flush Cache', 'action':'manage_cacheGC',
         'help':('OFSP','Database-Management_Flush-Cache.stx')},
        )
        )

    # These need to be here rather to make tabs work correctly. This
    # needs to be revisited.
    manage_activity=Globals.DTMLFile('dtml/activity', globals())
    manage_cacheParameters=Globals.DTMLFile('dtml/cacheParameters', globals())
    manage_cacheGC=Globals.DTMLFile('dtml/cacheGC', globals())


Globals.default__class_init__(DatabaseManager)

class FakeConnection:
    # Supports the methods of Connection that CacheManager needs

    def __init__(self, db, parent_jar):
        self._db = db
        self.version = parent_jar.getVersion()

    def db(self):
        return self._db

    def getVersion(self):
        return self.version

class DatabaseChooser (SimpleItem.SimpleItem):
    """Lets you choose which database to view
    """
    meta_type = 'Database Management'
    name = title = 'Database Management'
    icon = 'p_/DatabaseManagement_icon'
    isPrincipiaFolderish = 1

    manage_options=(
        {'label':'Databases', 'action':'manage_main'},
        )

    manage_main = PageTemplateFile('www/chooseDatabase.pt', globals())

    def __init__(self, id):
        self.id = id

    def getDatabaseNames(self):
        configuration = getConfiguration()
        names = configuration.dbtab.listDatabaseNames()
        names.sort()
        return names

    def __getitem__(self, name):
        configuration = getConfiguration()
        db = configuration.dbtab.getDatabase(name=name)
        m = AltDatabaseManager()
        m.id = name
        m._p_jar = FakeConnection(db, self.getPhysicalRoot()._p_jar)
        return m.__of__(self)

    def __bobo_traverse__(self, request, name):
        configuration = getConfiguration()
        if configuration.dbtab.hasDatabase(name):
            return self[name]
        return getattr(self, name)

    def tpValues(self):
        names = self.getDatabaseNames()
        res = []
        for name in names:
            m = AltDatabaseManager()
            m.id = name
            # Avoid opening the database just for the tree widget.
            m._p_jar = None
            res.append(m.__of__(self))
        return res

Globals.InitializeClass(DatabaseChooser)


class VersionManager(Fake, SimpleItem.Item, Acquisition.Implicit):
    """Version management"""
    manage=manage_main=DTMLFile('dtml/versionManager', globals())
    manage_main._setName('manage_main')
    id        ='Versions'
    name=title='Version Management'
    meta_type ='Version Management'
    icon='p_/VersionManagement_icon'

    manage_options=(
        (
        {'label':'Version', 'action':'manage_main',
         'help':('OFSP','Version-Management_Version.stx')},
        )
        )

Globals.default__class_init__(VersionManager)




# refcount snapshot info
_v_rcs=None
_v_rst=None

class DebugManager(Fake, SimpleItem.Item, Acquisition.Implicit):
    """Debug and profiling information"""
    manage=manage_main=DTMLFile('dtml/debug', globals())
    manage_main._setName('manage_main')
    id        ='DebugInfo'
    name=title='Debug Information'
    meta_type = name
    icon='p_/DebugManager_icon'

    manage_options=(
        (  {'label':'Debugging Info', 'action':'manage_main',
            'help':('OFSP','Debug-Information_Debug.stx')},
           {'label':'Profiling', 'action':'manage_profile',
            'help':('OFSP','Debug-Information_Profile.stx')},
           )
        )

    manage_debug=DTMLFile('dtml/debug', globals())

    def refcount(self, n=None, t=(type(Fake), type(Acquisition.Implicit))):
        # return class reference info
        dict={}
        for m in sys.modules.values():
            for sym in dir(m):
                ob=getattr(m, sym)
                if type(ob) in t:
                    dict[ob]=sys.getrefcount(ob)
        pairs=[]
        append=pairs.append
        for ob, v in dict.items():
            if hasattr(ob, '__module__'):
                name='%s.%s' % (ob.__module__, ob.__name__)
            else: name='%s' % ob.__name__
            append((v, name))
        pairs.sort()
        pairs.reverse()
        if n is not None:
            pairs=pairs[:n]
        return pairs

    def refdict(self):
        rc=self.refcount()
        dict={}
        for v, n in rc:
            dict[n]=v
        return dict

    def rcsnapshot(self):
        global _v_rcs
        global _v_rst
        _v_rcs=self.refdict()
        _v_rst=DateTime()

    def rcdate(self):
        return _v_rst

    def rcdeltas(self):
        if _v_rcs is None:
            self.rcsnapshot()
        nc=self.refdict()
        rc=_v_rcs
        rd=[]
        for n, c in nc.items():
            try:
                prev=rc[n]
                if c > prev:
                    rd.append( (c - prev, (c, prev, n)) )
            except: pass
        rd.sort()
        rd.reverse()
        return map(lambda n: {'name': n[1][2],
                              'delta': n[0],
                              'pc': n[1][1],
                              'rc': n[1][0]}, rd)

    def dbconnections(self):
        return Globals.DB.connectionDebugInfo()


    # Profiling support

    manage_profile=DTMLFile('dtml/profile', globals())

    def manage_profile_stats(self, sort='time', limit=200, stripDirs=1, mode='stats'):
        """Return profile data if available"""
        stats=getattr(sys, '_ps_', None)
        if stats is None:
            return None
        output=StringIO()
        stdout=sys.stdout
        if stripDirs:
            from copy import copy; stats= copy(stats)
            stats.strip_dirs()
        stats.sort_stats(sort)
        sys.stdout=output
        getattr(stats,'print_%s' % mode)(limit)
        sys.stdout.flush()
        sys.stdout=stdout
        return output.getvalue()

    def manage_getSysPath(self):
        return list(sys.path)

Globals.default__class_init__(DebugManager)




class ApplicationManager(Folder,CacheManager):
    """System management"""

    __roles__=('Manager',)
    isPrincipiaFolderish=1
    Database= DatabaseChooser('Database') #DatabaseManager()
    Versions= VersionManager()
    DebugInfo=DebugManager()
    DavLocks = DavLockManager()

    manage=manage_main=DTMLFile('dtml/cpContents', globals())
    manage_main._setName('manage_main')

    def version_txt(self):
        if not hasattr(self, '_v_version_txt'):
            self._v_version_txt=version_txt()

        return self._v_version_txt

    def sys_version(self): return sys.version
    def sys_platform(self): return sys.platform

    _objects=(
        {'id': 'Database',
         'meta_type': Database.meta_type},
        {'id': 'Versions',
         'meta_type': Versions.meta_type},
        {'id': 'DavLocks',
         'meta_type': DavLocks.meta_type},
        {'id': 'Products',
         'meta_type': 'Product Management'},
        {'id': 'DebugInfo',
         'meta_type': DebugInfo.meta_type},
        )

    manage_options=(
        (
        {'label':'Contents', 'action':'manage_main',
         'help':('OFSP','Control-Panel_Contents.stx')},
        )
        +Undo.UndoSupport.manage_options
        )

    id        ='Control_Panel'
    name=title='Control Panel'
    meta_type ='Control Panel'
    icon='p_/ControlPanel_icon'

    process_id=os.getpid()
    process_start=int(time.time())

    # Disable some inappropriate operations
    manage_addObject=None
    manage_delObjects=None
    manage_addProperty=None
    manage_editProperties=None
    manage_delProperties=None

    def __init__(self):
        self.Products=ProductFolder()


# Note by brian:
#
# This __setstate__ does not seem to work - it creates a new ProductFolder
# and adds it to the CP instance if needed, but the resulting PF does not
# seem to be persistent ;( Rather than spend much time figuring out why,
# I just added a check in Application.open_bobobase to create the PF if
# it is needed (this is where several other b/c checks are done anyway.)
#
#
#    def __setstate__(self, v):
#        ApplicationManager.inheritedAttribute('__setstate__')(self, v)
#        if not hasattr(self, 'Products'):
#            self.Products=ProductFolder()


    def _canCopy(self, op=0):
        return 0

    def _init(self):
        pass

    def manage_app(self, URL2):
        """Return to the main management screen"""
        raise Redirect, URL2+'/manage'

    def process_time(self):
        s=int(time.time())-self.process_start
        d=int(s/86400)
        s=s-(d*86400)
        h=int(s/3600)
        s=s-(h*3600)
        m=int(s/60)
        s=s-(m*60)
        d=d and ('%d day%s'  % (d, (d != 1 and 's' or ''))) or ''
        h=h and ('%d hour%s' % (h, (h != 1 and 's' or ''))) or ''
        m=m and ('%d min' % m) or ''
        s='%d sec' % s
        return '%s %s %s %s' % (d, h, m, s)

    def thread_get_ident(self): return get_ident()

    def db_name(self):
        return self._p_jar.db().getName()

    def db_size(self):
        s=self._p_jar.db().getSize()
        if type(s) is type(''):
            return s

        if s >= 1048576.0: return '%.1fM' % (s/1048576.0)
        return '%.1fK' % (s/1024.0)

    if os.environ.has_key('ZMANAGED'):
        manage_restartable=1
        def manage_restart(self, URL1):
            """Shut down the application"""
            try:
                user = '"%s"' % getSecurityManager().getUser().getUserName()
            except:
                user = 'unknown user'
            zLOG.LOG("ApplicationManager", zLOG.INFO,
                     "Restart requested by %s" % user)
            #for db in Globals.opened: db.close()
            Lifetime.shutdown(1)
            return """
            
            
            Zope is restarting
            """ % escape(URL1, 1)

    def manage_shutdown(self):
        """Shut down the application"""
        try:
            user = '"%s"' % getSecurityManager().getUser().getUserName()
        except:
            user = 'unknown user'
        zLOG.LOG("ApplicationManager", zLOG.INFO,
                 "Shutdown requested by %s" % user)
        #for db in Globals.opened: db.close()
        Lifetime.shutdown(0)
        return """
        
        
        Zope is shutting down
        """

    def manage_pack(self, days=0, REQUEST=None):
        """Pack the database"""

        t=time.time()-days*86400

        db=self._p_jar.db()
        t=db.pack(t)
        if REQUEST is not None:
            REQUEST['RESPONSE'].redirect(
                REQUEST['URL1']+'/manage_workspace')
        return t

    def revert_points(self): return ()

    def version_list(self):
        # Return a list of currently installed products/versions
        path_join=os.path.join
        isdir=os.path.isdir
        exists=os.path.exists

        cfg = getConfiguration()
        product_dir=path_join(cfg.softwarehome,'Products')
        product_names=os.listdir(product_dir)
        product_names.sort()
        info=[]
        for product_name in product_names:
            package_dir=path_join(product_dir, product_name)
            if not isdir(package_dir):
                continue
            version_txt = None
            for name in ('VERSION.TXT', 'VERSION.txt', 'version.txt'):
                v = path_join(package_dir, name)
                if exists(v):
                    version_txt = v
                    break
            if version_txt is not None:
                file=open(version_txt, 'r')
                data=file.readline()
                file.close()
                info.append(data.strip())
        return info


    def version_info(self):
        r=[]
        try: db=self._p_jar.db()
        except: raise ValueError, """
        Sorry, Version management is only supported if you use ZODB 3.
        """
        for v in db.versions():
            if db.versionEmpty(v): continue
            r.append({'id': v})
        return r

    def manage_saveVersions(self, versions, REQUEST=None):
        "Commit some versions"
        db=self._p_jar.db()
        for v in versions:
            db.commitVersion(v)
        if REQUEST is not None:
            REQUEST['RESPONSE'].redirect(REQUEST['URL1']+'/manage_main')

    def manage_discardVersions(self, versions, REQUEST=None):
        "Discard some versions"
        db=self._p_jar.db()
        for v in versions:
            db.abortVersion(v)
        if REQUEST is not None:
            REQUEST['RESPONSE'].redirect(REQUEST['URL1']+'/manage_main')

    def getSOFTWARE_HOME(self):
        return getConfiguration().softwarehome

    def getZOPE_HOME(self):
        return getConfiguration().zopehome

    def getINSTANCE_HOME(self):
        return getConfiguration().instancehome

    def getCLIENT_HOME(self):
        return getConfiguration().clienthome

    def getServers(self):
        # used only for display purposes
        # return a sequence of two-tuples.  The first element of
        # each tuple is the service name, the second is a string repr. of
        # the port/socket/other on which it listens
        from asyncore import socket_map
        l = []
        for k,v in socket_map.items():
            # this is only an approximation
            if hasattr(v, 'port'):
                type = str(getattr(v, '__class__', 'unknown'))
                port = v.port
                l.append((str(type), 'Port: %s' % port))
        return l

    def objectIds(self, spec=None):
        """ this is a patch for pre-2.4 Zope installations. Such
            installations don't have an entry for the WebDAV LockManager
            introduced in 2.4.
        """

        meta_types = map(lambda x: x.get('meta_type',None) , self._objects)

        if not self.DavLocks.meta_type in meta_types:

            lst = list(self._objects)
            lst.append(  {'id': 'DavLocks', \
                'meta_type': self.DavLocks.meta_type})
            self._objects = tuple(lst)

        return Folder.objectIds(self, spec)

class AltDatabaseManager(DatabaseManager, CacheManager):
    """Database management DBTab-style
    """
    db_name = ApplicationManager.db_name.im_func
    db_size = ApplicationManager.db_size.im_func
    manage_pack = ApplicationManager.manage_pack.im_func

Zope-2.9.4-retire_zpkg/lib/python/App/ZApplication.py0000644000175000017500000000524010237662444022461 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2001, 2002 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Implement an bobo_application object that is BoboPOS3 aware

This module provides a wrapper that causes a database connection to be created
and used when bobo publishes a bobo_application object.
"""

import transaction

connection_open_hooks = []

class ZApplicationWrapper:

    def __init__(self, db, name, klass= None, klass_args= (),
                 version_cookie_name=None):
        self._stuff = db, name, version_cookie_name
        if klass is not None:
            conn=db.open()
            root=conn.root()
            if not root.has_key(name):
                root[name]=klass()
                transaction.commit()
            conn.close()
            self._klass=klass


    # This hack is to overcome a bug in Bobo!
    def __getattr__(self, name):
        return getattr(self._klass, name)

    def __bobo_traverse__(self, REQUEST=None, name=None):
        db, aname, version_support = self._stuff
        if version_support is not None and REQUEST is not None:
            version=REQUEST.get(version_support,'')
        else: version=''
        conn=db.open(version)

        if connection_open_hooks:
            for hook in connection_open_hooks:
                hook(conn)

        # arrange for the connection to be closed when the request goes away
        cleanup = Cleanup(conn)
        REQUEST._hold(cleanup)

        conn.setDebugInfo(REQUEST.environ, REQUEST.other)

        v=conn.root()[aname]

        if name is not None:
            if hasattr(v, '__bobo_traverse__'):
                return v.__bobo_traverse__(REQUEST, name)

            if hasattr(v,name): return getattr(v,name)
            return v[name]

        return v


    def __call__(self, connection=None):
        db, aname, version_support = self._stuff

        if connection is None:
            connection=db.open()
        elif isinstance(connection, basestring):
            connection=db.open(connection)

        return connection.root()[aname]


class Cleanup:
    def __init__(self, jar):
        self._jar = jar

    def __del__(self):
        self._jar.close()
Zope-2.9.4-retire_zpkg/lib/python/App/dtml/0000755000175000017500000000000010447233616020447 5ustar  tseavertseaverZope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_top_frame.dtml0000644000175000017500000000251710050234363024610 0ustar  tseavertseaver


















Logged in as &dtml-AUTHENTICATED_USER;   

 

 












Zope-2.9.4-retire_zpkg/lib/python/App/dtml/versionManager.dtml0000644000175000017500000000207510050234363024303 0ustar  tseavertseaver





Select one or more versions below and then click on the "Save"
button to save the versions or click on the "Discard" button to
discard changes made in the versions.






  

  

    
    
    
    
    

    &dtml-id;
    

    		
  

  
  

    
    
    

    
        
    
    

    		
  

  







There are no non-empty versions.





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/cpContents.dtml0000644000175000017500000000700010050234363023434 0ustar  tseavertseaver




The Control Panel provides access to system information and management 
functions such as database and product management.  









  
  

  Zope Version
  

  		
  
  

  &dtml-version_txt;
  

  		




  
  

  Python Version
  

  		
  
  

  &dtml-sys_version;
  

  		




  
  

  System Platform
  

  		
  
  

  &dtml-sys_platform;
  

  		




  
  

  SOFTWARE_HOME
  

  		
  
  

  &dtml-getSOFTWARE_HOME;
  

  		




  
  

  ZOPE_HOME
  

  		
  
  

  &dtml-getZOPE_HOME;
  

  		




  
  

  INSTANCE_HOME
  

  		
  
  

  &dtml-getINSTANCE_HOME;
  

  		




  
  

  CLIENT_HOME
  

  		
  
  

  &dtml-getCLIENT_HOME;
  

  		




  
  

  Network Services
  

  		
  
  

  
    &dtml-sequence-key; (&dtml-sequence-item;)

  
  

  		




  
  

  Process Id
  

  		
  
  

  &dtml-process_id; (&dtml-thread_get_ident;)
  

  		




  
  

  Running For
  

  		
  
  

  &dtml-process_time;
  

  		





  
   
  
  
  

  
  
  
  
  

  		














  
  
  
  
  
  

  
  &dtml-title;
  
  
    
      This item has been modified in this version
    
      This item has been modified in another version
    
  
  

  		









Zope-2.9.4-retire_zpkg/lib/python/App/dtml/addFactory.dtml0000644000175000017500000000413410050234363023401 0ustar  tseavertseaver





A Factory allows you to place entries in the Zope Product add list. In the 
form below the add list name is the name under which your entry will 
appear in the Zope Product add list. The method is the method that 
will be invoked when a user adds a new object.  This must be one of the 
objects in the product, typically a Python Script or DTML object.








  

    
    

    Id
    

    		
    
    
    
  


  

    
    

    Title
    

    		
    
    
    
  


  

    
    

    Add list name
    

    		
    
    
    
  

  
  

    
    

    Method
    

    		
    
    

    
  

  		
  


  

  
  
  

  

  
  

  		
  





      



Before you can define a factory, you have to define one or more "methods", 
such as Document or other objects that do the factory's work.






Zope-2.9.4-retire_zpkg/lib/python/App/dtml/addProduct.dtml0000644000175000017500000000217710050234363023417 0ustar  tseavertseaver





Products allows you to define new types of Zope objects. A Product contains 
other objects including a Factory which allows you to make your Product 
objects available via the Product add list.







  

    
    

    Id
    

    		
    
    
    
  


  

    
    

    Title
    

    		
    
    
    
  


  

    
    
    

    

    
    

    		
  







Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage.dtml0000644000175000017500000000216210050234363022550 0ustar  tseavertseaver


Zope on &dtml-BASE0;





  
  
  
  
  
  


  
    
    
  


  




Management interfaces require the use of a <B>frames-capable</B> web browser.



Zope-2.9.4-retire_zpkg/lib/python/App/dtml/debug.dtml0000644000175000017500000000550710050234363022414 0ustar  tseavertseaver


<dtml-if title>&dtml-title;</dtml-if>



















Debug Information






    

  • Zope version: &dtml-version_txt;

  • Python version: &dtml-sys_version;

  • System Platform: &dtml-sys_platform;

  • SOFTWARE_HOME: &dtml-getSOFTWARE_HOME;

  • INSTANCE_HOME: &dtml-getINSTANCE_HOME;

  • CLIENT_HOME: &dtml-getCLIENT_HOME;

  • Process ID: &dtml-process_id; (&dtml-thread_get_ident;)

  • Running for: &dtml-process_time;

  • sys.path: 
     
   &dtml-sequence-item;
      

  • Top Refcounts:


    




    

    

Class








Delta


    


    

&dtml-name;


&dtml-pc;


&dtml-rc;


+&dtml-delta;


    


    


    Cache detail |
Cache extreme detail

    

    Update Snapshot | 

  Stop auto refresh

  Refresh |
  Auto refresh interval (seconds):
  
  


    


  • Connections:

  
    

    openedinfoversion
    

    &dtml-opened;&dtml-info;&dtml-version;
    

    










Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_page_style.css.dtml0000644000175000017500000000562610254326517025574 0ustar  tseavertseaver



h1 {
  font-family: Verdana, Helvetica, sans-serif; 
  font-size: 24pt; 
  font-weight: bold; 
}

h2 {
  font-family: Verdana, Helvetica, sans-serif; 
  font-size: 18pt; 
  font-weight: bold; 
}

h3 {
  font-family: Verdana, Helvetica, sans-serif; 
  font-size: 14pt; 
  font-weight: bold; 
}

a:hover {  
  font-family: Verdana, Helvetica, sans-serif; 
  text-decoration: underline;
  color: #333333; 
}

a:link {
  font-family: Verdana, Helvetica, sans-serif; 
  text-decoration: none;
  color: #000099;
}

a {
  font-family: Verdana, Helvetica, sans-serif; 
  text-decoration: none;
  color: #000099;
}

a.strong-link {
  font-family: Verdana, Helvetica, sans-serif;
  text-decoration: underline;
  color: #000099;
}

p {
  font-family: Verdana, Helvetica, sans-serif;
  font-size: 10pt;
  color: #333333;
}

th {
  font-family: Verdana, Helvetica, sans-serif; 
  font-weight: bold;
  font-size: 10pt; 
  color: #333333;
}

.form-help {
  font-family: Verdana, Helvetica, sans-serif;
  font-size: 10pt;
  color: #333333;
}

.std-text {
  font-family: Verdana, Helvetica, sans-serif;
  font-size: 10pt;
  color: #333333;
}

.tab-small {
  font-family: Verdana, Helvetica, sans-serif; 
  font-size: 8pt; 
  color: #333333;
}

.location-bar {
  background-color: #efefef;
  border: none;
}

.strong-header {
  font-family: Verdana, Helvetica, sans-serif;
  font-size: 12pt;
  font-weight: bold;
  background-color: #000000;
  color: #ffffff;
}

.list-header {
  background-color: #c0c0c0;
  border: none;
}

.list-item {
  font-family: Verdana, Helvetica, sans-serif; 
  font-size: 10pt; 
}

.list-nav {
  font-family: Verdana, Helvetica, sans-serif; 
  font-size: 10pt; 
  font-weight: bold;
}

.row-normal {
  background-color: #ffffff;
  border: none;

}

.row-hilite {
  background-color: #efefef;
  border: none;
}

.section-bar {
  background-color: #c0c0c0;
  border: none;
}

.system-msg {
  font-family: Verdana, Helvetica, sans-serif; 
  font-size: 10pt; 
  background-color: #ffffff;
  border:  1px solid #000000;
  margin-bottom: 6px;
  margin-top: 6px;
  padding: 4px;
  color: #660033;
}

.form-title {
  font-family: Verdana, Helvetica, sans-serif; 
  font-weight: bold;
  font-size: 12pt; 
  color: #333333;
}

.form-label {
  font-family: Verdana, Helvetica, sans-serif; 
  font-weight: bold;
  font-size: 10pt; 
  color: #333333;
}

.form-optional {
  font-family: Verdana, Helvetica, sans-serif; 
  font-weight: bold;
  font-style: italic;
  font-size: 10pt; 
  color: #333333;
}

.form-element {
  font-family: Verdana, Helvetica, aans-serif;
  font-size: 10pt;
  color: #000000;
}

.form-text {
  font-family: Verdana, Helvetica, sans-serif;
  font-size: 10pt;
  color: #333333;
}

.form-mono {
  font-family: monospace;
  font-size: 12px;
  text-decoration: none;
}
Zope-2.9.4-retire_zpkg/lib/python/App/dtml/zope_quick_start.dtml0000644000175000017500000000772610104173243024720 0ustar  tseavertseaver


Zope QuickStart

















You have not created any users in this Zope instance.  In order to
log in and manage this Zope instance, you'll need to add an adminstrative
user account.





If you're running Zope on UNIX or Linux, you can create an administrative
user account via the "zopectl adduser" command from a shell.  Note: You'll
need to shut Zope itself down before "zopectl adduser" will work.  Restart
Zope after executing this command in order to log in.





If you're running Zope on Windows, you'll need to use the "zpasswd.py" utility
in your Zope installation's "bin" directory at
\bin
to create a file named inituser in your Zope instance home at
 that contains the
initial administrative username and password.









Welcome to Zope, a high-performance object-oriented 
platform for building dynamic Web applications. Here are some quick 
pointers to get you started:




    

  • 

    
Read The 
Fine Manual.  This document guides you through the whole process of
learning Zope, from logging in for the first time to creating your own
web applications.

    

    • 


  • 

    
There is a built-in interactive Zope Tutorial which 
gets you started with some simple tasks using the Zope managment 
interface. To use the tutorial, go to any Folder and select 
Zope Tutorial from the add list and click the Add 
button. Provide a name for the tutorial and click Add to 
begin working with the tutorial.

    

    • 


  • 

    
Import
and then check out the new example Zope
applications. These examples show you simple working Zope
applications that you can copy and modify.

    

    • 


  • 

    
Go to the main 
Documentation Overview on Zope.org.  Here you will find pointers to 
official and community contributed documentation.

    

    • 


  • 

    
Look at the various Mailing 
Lists about Zope.  The Mailing Lists are where you can get 
quick, accurate, friendly help from a large community of Zope 
users from around the world.

    

    • 


  • 

    
Browse and search the integrated, 
Online Help System which contains documentation on 
the various kinds of components you'll find in Zope.

    

    • 


  • 

    
Go directly to the 
Zope Management Interface if you'd like to start working with Zope 
right away.  NOTE:  Some versions of Microsoft Internet Explorer,
(specifically IE 5.01 and early versions of IE 5.5) may have problems
displaying Zope management pages.  If you cannot view the management pages,
try upgrading your IE installation to the latest release version, or use
a different browser.

    

    • 


  • 

    
Find out about Zope 
Corporation, the publishers of Zope.

    

    • 






Zope-2.9.4-retire_zpkg/lib/python/App/dtml/cacheParameters.dtml0000644000175000017500000000433210127020541024404 0ustar  tseavertseaver








  
  

  Total number of objects in the database
  

  		
  
  

  &dtml-database_size;
  

  		





  
  

  Total number of objects in memory from all caches
  

  		
  
  

  &dtml-cache_length;
  

  		





  
  

  Target number of objects in memory per cache
  

  		
  
  

  &dtml-cache_size;
  

  		





  
  

  Total number of objects in each cache:
  

  		





    
Cache Name

    
Number of active objects

    
Total active and non-active objects







    
&dtml-connection;

    
&dtml-ngsize;

    
&dtml-size;






    
Total

    
&dtml-cache_length;

    








  
Cache Details


  
      
Object ClassCount

    
&dtml-sequence-key;&dtml-sequence-item;

    
  




  
Objects in the cache


  
      
Object ID
             Object Class
             Reference Count
             References
          

    
&dtml-oid;
          &dtml-klass;
          &dtml-rc;
          &dtml-references;
      

    
  





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/editPermission.dtml0000644000175000017500000000163310050234363024320 0ustar  tseavertseaver








  
  

  Id
  

  		
  
  

  &dtml-id;
  

  		





  
  

  Title
  

  		
  
  
  





  
  

  Name
  

  		
  
  
  





  
  
  

  
  

  		








Zope-2.9.4-retire_zpkg/lib/python/App/dtml/dbMain.dtml0000644000175000017500000000240110050234363022506 0ustar  tseavertseaver




The Database Manager allows you to view database status information.
It also allows you to perform maintenance tasks such as database packing 
and cache management.







  
  

  Database Location
  

  		
  
  

  &dtml-db_name;
  

  		




  
  

  Database Size
  

  		
  
  

  &dtml-db_size;
  

  		













  
  
  Click pack to pack the Zope database, removing previous revisions 
  of objects that are older than
  
   days.
  
  
  

  
  

  		









Zope-2.9.4-retire_zpkg/lib/python/App/dtml/addPermission.dtml0000644000175000017500000000220010050234363024112 0ustar  tseavertseaver







  

    
    

    Id
    

    		
    
    
    
  


  

    
    

    Title
    

    		
    
    
    
  


  

    
    

    Name
    

    		
    
    
    
  


  

    
    
    

    

    
    

    		
  







Zope-2.9.4-retire_zpkg/lib/python/App/dtml/activity.dtml0000644000175000017500000000502110050234363023151 0ustar  tseavertseaver


Recent Database Activity







 Keep History (seconds)
 
  

   
   
  

 		




 Displayed Range
 &dtml-start_time; to

     &dtml-end_time;		




 
 
  

   
  

 		










 
 
 
 
 














 Object stores
&dtml-store_count;

   Total:
   &dtml-total_store_count;
 






 Object loads
&dtml-load_count;

   Total:
   &dtml-total_load_count;
 






 Connections
&dtml-connections;

   Total:
   &dtml-total_connections;
 






 
&dtml-time_offset;

 












Zope-2.9.4-retire_zpkg/lib/python/App/dtml/readme.dtml0000644000175000017500000000022010050234363022546 0ustar  tseavertseaver





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/davLockManager.dtml0000644000175000017500000000565710050234363024212 0ustar  tseavertseaver






 
All locked objects
 from path &dtml-frompath;
 are listed below.


 
No locked objects
 from path &dtml-frompath;
 were found.






Search for locked objects starting from path:












 

  Locked Item
  Lock Info
 





 
  
  

 

 

 

 
  
 
 
  
  [&dtml-meta_type;]
  
 
 
  
 
 
  
   Owner: &dtml-owner;,
   Token: &dtml-token;

  
 		
 

 




  






Zope-2.9.4-retire_zpkg/lib/python/App/dtml/refresh.dtml0000644000175000017500000000722510050234363022763 0ustar  tseavertseaver
  Arguments for this method:
   id, refresh_txt, error_type, error_value, error_tb, devel_mode,
   auto_refresh_enabled, auto_refresh_other, dependent_products,
   loaded_modules



 

 
 
 
 &dtml-form_title;
 
 
 
&dtml-form_title;






 
The refresh function, designed to ease the development of Zope
 products, is not currently enabled for this product.
 To make it available, put a file named "refresh.txt" in the &dtml-id;
 product directory.  Please note that not all products are
 compatible with the refresh function.



 
  
An exception occurred during the last refresh.

   Exception type: &dtml-error_type; 

   Exception value: &dtml-error_value;
  

  
&dtml-error_tb;

  

 

 

  

   

    

     
      

       Important information about refreshing this product:

       
      

     

     

     


     

      
       
       Auto refresh is enabled.  Zope will repeatedly scan for
       changes to the Python modules that make up this product and
       execute a refresh when needed.
       
       Although auto refresh is enabled, Zope is not in development
       mode so auto refresh is not available.  Use the "-D" argument
       when starting Zope to enable development mode.
       
      
       Auto refresh is disabled.  Enable auto refresh
       to cause Zope to frequently scan this product for changes.
       Note that auto refresh can slow down Zope considerably
       if enabled for more than a few products.
      
      

      
       
       Auto refresh mode  
       
      
     


     
      
Select dependent auto-refreshable products to be refreshed
      simultaneously.

      
       
        
        &dtml-sequence-item;

       
      
      
      

     

    		
    

     
Refreshable product modules:

     
    
      
       
  • &dtml-sequence-item;
    • 
          
     


    		
   

  

 




  

  

Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_page_header.dtml0000644000175000017500000000201310102514570025046 0ustar  tseavertseaver


















Zope-2.9.4-retire_zpkg/lib/python/App/dtml/profile.dtml0000755000175000017500000000437010050234363022766 0ustar  tseavertseaver






Profiling information is generated using the standard Python 
profiler. To learn how to interpret the profiler statistics, 
see the 
Python profiler documentation.










Sort: 
    

Limit: 
    

strip Dirs: 
    
    checked>

Mode: 
    













&dtml-stats;








Profiling is not currently enabled or there is not yet any profiling
data to report.  To enable profiling, restart the Zope process with
the configuration setting 'publisher-profile-file' defined. The value
of this variable should be the full system path to a file that will be
used to dump a profile report when the process restarts or exits.






Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_page_footer.dtml0000644000175000017500000000002010050234363025111 0ustar  tseavertseaver

Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_tabs.dtml0000644000175000017500000001347310050234363023570 0ustar  tseavertseaver















  
  


  
  

  
  

  
  




    
  
  ">






  
  
  

  
  
  






 href="&dtml-action;"href="&dtml-URL1;" target="&dtml-target;"> 
 href="&dtml-action;"href="&dtml-URL1;" target="&dtml-target;"> 


























  

  
  
  
  
  
  

  

    
    

    
    &dtml-meta_type;
    
    
    
      
    &dtml-meta_type;
      
    &dtml-meta_type;
      
    
    Object
     
    at 
    
    
      
        This item has been modified in this version
      
        This item has been modified in another version
              (&dtml-locked_in_version;)
      
    
    
     This item has been locked by WebDAV
    
    

    		
  
  

  
  

  		
  
  

  
  

  		
  
  
  
  
  

  





You are currently working in version &dtml-Zope-Version;








 
()





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/copyright.dtml0000644000175000017500000002006610337376242023346 0ustar  tseavertseaver


Zope Copyright





Zope License |
Python License |
Zope Credits






Zope Public License (ZPL) Version 2.1


This software is Copyright ©
Zope Corporation™ and
Contributors. All rights reserved.




This license has been certified as open source. It has also
been designated as GPL compatible by the Free Software
Foundation (FSF).





Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:




    


  1. 
Redistributions in source code must retain the
   accompanying copyright notice, this list of conditions,
   and the following disclaimer.

    2. 

  2. 
Redistributions in binary form must reproduce the accompanying
   copyright notice, this list of conditions, and the
   following disclaimer in the documentation and/or other
   materials provided with the distribution.

    3. 

  3. 
Names of the copyright holders must not be used to
   endorse or promote products derived from this software
   without prior written permission from the copyright
   holders.

    4. 

  4. 
The right to distribute this software or to use it for
   any purpose does not give you the right to use
   Servicemarks (sm) or Trademarks (tm) of the copyright
   holders. Use of them is covered by separate agreement
   with the copyright holders.

    5. 

  5. 
If any files are modified, you must cause the modified
   files to carry prominent notices stating that you changed
   the files and the date of any change.

    6. 




Disclaimer




  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS ``AS IS''
  AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
  NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN
  NO EVENT SHALL THE COPYRIGHT HOLDERS BE
  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
  OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  DAMAGE.







This software consists of contributions made by Zope
Corporation and many individuals on behalf of Zope
Corporation.  Specific attributions are listed in the
accompanying credits file.











This software is powered by Python!



Copyright © 1991-1995 by Stichting Mathematisch Centrum, Amsterdam,
The Netherlands.



All Rights Reserved



Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the names of Stichting Mathematisch
Centrum or CWI or Corporation for National Research Initiatives or
CNRI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.



While CWI is the initial source for this software, a modified version
is made available by the Corporation for National Research Initiatives
(CNRI) at the Internet address
ftp://ftp.python.org.



STICHTING MATHEMATISCH CENTRUM AND CNRI DISCLAIM ALL WARRANTIES WITH
REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH
CENTRUM OR CNRI BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
PERFORMANCE OF THIS SOFTWARE.





Zope uses the xmlrpclib module:


Copyright © 1999 by Secret Labs AB

Copyright © 1999 by Fredrik Lundh



By obtaining, using, and/or copying this software and/or its
associated documentation, you agree that you have read, understood,
and will comply with the following terms and conditions:



Permission to use, copy, modify, and distribute this software and its
associated documentation for any purpose and without fee is hereby
granted, provided that the above copyright notice appears in all
copies, and that both that copyright notice and this permission notice
appear in supporting documentation, and that the name of Secret Labs
AB or the author not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.



SECRET LABS AB AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS.  IN NO EVENT SHALL SECRET LABS AB OR THE AUTHOR BE LIABLE FOR
ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.





Zope uses the C expat library by James Clark, for parsing XML text.



Copyright (c) 1998, 1999 James Clark.  Expat is subject to the Mozilla Public
License Version 1.1.









Zope Credits





  The Zope software receives contributions from far and wide.  Here's
  the Zope Hall of Fame:



 

 Paul Everitt, paul@zope.com.





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/menu.dtml0000644000175000017500000000436510050234363022273 0ustar  tseavertseaver







  
  
  &dtml-meta_type; 
  
  
  
  
  
  Root Folder
  
  &dtml-id;
  
  
  
  
  






&dtml-meta_type; 

&dtml-id;





  
  
  
  
  © Zope Corporation
  
  
  




  
  
  
  Refresh
  
  















Logged in as &dtml-AUTHENTICATED_USER;   


 

 













Zope-2.9.4-retire_zpkg/lib/python/App/dtml/undo.dtml0000644000175000017500000000577010050234363022275 0ustar  tseavertseaver









This application's transactional feature allows you to easily undo changes 
made to the application's settings or data. You can revert the application 
to a "snapshot" of its state at a previous point in time.





Select one or more transactions below and then click on the "Undo"
button to undo those transactions.  Note that even though a transaction
is shown below, you may not be able to undo it if later transactions
modified objects that were modified by a selected transaction.










  

    
    


    &last_transaction:int=&dtml-first_transaction;&PrincipiaUndoBatchSize:int=&dtml-PrincipiaUndoBatchSize;"
     onMouseOver="window.status='View later transactions'; return true"
     onMouseOut="window.status=''; return true">< Later Transactions

     

    

    		

    
    


    &PrincipiaUndoBatchSize:int=&dtml-PrincipiaUndoBatchSize;"
     onMouseOver="window.status='View earlier transactions'; return true"
     onMouseOut="window.status=''; return true">Earlier Transactions >
 
     

    

    		
  





   
  
  






    
    
    
    
    

    &dtml-description; by &dtml-user_name;Zope
    

    		
    
    

    
    

    		
  


  

    
    
    

    
    

    		
  








There are no transactions that can be undone.







Zope-2.9.4-retire_zpkg/lib/python/App/dtml/editFactory.dtml0000644000175000017500000000355610050234363023605 0ustar  tseavertseaver




The initial method is the method that will be invoked 
when a user adds a new object.  This must be one of the objects in the 
product, typically a Document.









  
  

  Id
  

  		
  
  

  &dtml-id;
  

  		





  
  

  Title
  

  		
  
  
  


  


  
  

  Add list name
  

  		
  
  
  


  


  
  

  Initial method
  

  		
  
  

  
  

  		





  
  

  Permission
  

  		
  
  

  
  






  
  
  

  
  

  		














Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_zmi_prefs.dtml0000644000175000017500000000620710050234363024632 0ustar  tseavertseaver




  
  
  
  
  
  




This form lets you tweak the Zope management interface to fit
your browser.  Note that you need to press the browser reload
button in order for some changes to take effect.













  
  

  Show Top Frame
  

  		
  
  

  
  checked="checked"
    /> Yes
  checked="checked"
    /> No
  
  

  		





  
  

  Use Style Sheets
  

  		
  
  

  
  checked="checked"
    /> Yes
  checked="checked"
    /> No
  
  

  		





  
  

  Text Area Width
  

  		
  
  
  





  
  

  Text Area Height
  

  		
  
  
  











  
          









Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_style_test.dtml0000644000175000017500000000723010050234363025030 0ustar  tseavertseaver


System Stylesheet Test




&dtml-HTTP_USER_AGENT;


Text Styles




This is small-st. 
This is small-st. 
This is small-st. 
This is small-st. 





This is small-un. 
This is small-un. 
This is small-un. 
This is small-un. 





This is small-em. 
This is small-em. 
This is small-em. 
This is small-em. 





This is small-tx. 
This is small-tx. 
This is small-tx. 
This is small-tx. 





This is normal-st. 
This is normal-st. 
This is normal-st. 
This is normal-st. 





This is normal-un. 
This is normal-un. 
This is normal-un. 
This is normal-un. 





This is normal-em. 
This is normal-em. 
This is normal-em. 
This is normal-em. 






This is normal-tx. 
This is normal-tx. 
This is normal-tx. 
This is normal-tx. 





This is large-st. 
This is large-st. 
This is large-st. 
This is large-st. 





This is large-un. 
This is large-un. 
This is large-un. 
This is large-un. 





This is large-em. 
This is large-em. 
This is large-em. 
This is large-em. 





This is large-tx. 
This is large-tx. 
This is large-tx. 
This is large-tx. 








This is some text. This is some text. This is some text. 
This is some text. This is some text. This is some text. 
This is some text. This is some text. This is some text. 
This is some text. This is some text. This is some text. 
This is some text. This is some text. This is some text. 
This is some text. This is some text. This is some text. 








Form Elements

























 This is option 1

 This is option 2

 This is option 3








 This is option 1

 This is option 2

 This is option 3

















 
 
 
 





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/distributionView.dtml0000644000175000017500000000265710050234363024703 0ustar  tseavertseaver




You can create a packaged version of this product that can be 
distributed to other Zope users using the form below.








  
  

  Version
  

  		
  
  
  




  
  

  Policy
  

  		
  
  

   
  Allow redistribution
  

   Disallow 
   redistribution and allow user to configure 
  
    
  only the objects  selected below
  

  		




  
  
  
  




  
  
  

  
  

  		







Zope-2.9.4-retire_zpkg/lib/python/App/dtml/manage_form_title.dtml0000644000175000017500000000073310050234363024776 0ustar  tseavertseaver




  
  

  &dtml-form_title;
  

  		
  
  

  
  
  
   
  
  

  		





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/cacheGC.dtml0000644000175000017500000000242710127020541022575 0ustar  tseavertseaver









  
  

  Minimize
  

  		




  
  

  Remove all objects from all ZODB in-memory caches
  

  
  

  

  
  

  

  		







  
Cache Details


  
      
Object ClassCount

    
&dtml-sequence-key;&dtml-sequence-item;

    
  




  
Objects in the cache


  
      
Object ID
             Object Class
             Reference Count
             References
          

    
&dtml-oid;
          &dtml-klass;
          &dtml-rc;
          &dtml-references;
      

    
  





Zope-2.9.4-retire_zpkg/lib/python/App/dtml/traceback.dtml0000644000175000017500000000022010050234363023230 0ustar  tseavertseaver



Import Traceback



&dtml-import_error_;



Zope-2.9.4-retire_zpkg/lib/python/App/tests/0000755000175000017500000000000010447233616020651 5ustar  tseavertseaverZope-2.9.4-retire_zpkg/lib/python/App/tests/test_setConfiguration.py0000644000175000017500000000674210337373524025617 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Tests for App.config.setConfiguration()
"""

import os, sys, unittest

import Testing
import Zope2
Zope2.startup()

import App.config
import App.FindHomes
import Globals
import __builtin__


class SetConfigTests(unittest.TestCase):

    def setUp(self):
        # Save away everything as we need to restore it later on
        self.clienthome = self.getconfig('clienthome')
        self.instancehome = self.getconfig('instancehome') 
        self.softwarehome = self.getconfig('softwarehome')
        self.zopehome = self.getconfig('zopehome')
        self.debug_mode = self.getconfig('debug_mode')

    def tearDown(self):
        self.setconfig(clienthome=self.clienthome,
                       instancehome=self.instancehome,
                       softwarehome=self.softwarehome,
                       zopehome=self.zopehome,
                       debug_mode=self.debug_mode)

    def getconfig(self, key):
        config = App.config.getConfiguration()
        return getattr(config, key, None)

    def setconfig(self, **kw):
        config = App.config.getConfiguration()
        for key, value in kw.items():
            setattr(config, key, value)
        App.config.setConfiguration(config)

    def testClientHomeLegacySources(self):
        self.setconfig(clienthome='foo')
        self.assertEqual(os.environ.get('CLIENT_HOME'), 'foo')
        self.assertEqual(App.FindHomes.CLIENT_HOME, 'foo')
        self.assertEqual(__builtin__.CLIENT_HOME, 'foo')
        self.assertEqual(Globals.data_dir, 'foo')

    def testInstanceHomeLegacySources(self):
        self.setconfig(instancehome='foo')
        self.assertEqual(os.environ.get('INSTANCE_HOME'), 'foo')
        self.assertEqual(App.FindHomes.INSTANCE_HOME, 'foo')
        self.assertEqual(__builtin__.INSTANCE_HOME, 'foo')
        self.assertEqual(Globals.INSTANCE_HOME, 'foo')

    def testSoftwareHomeLegacySources(self):
        self.setconfig(softwarehome='foo')
        self.assertEqual(os.environ.get('SOFTWARE_HOME'), 'foo')
        self.assertEqual(App.FindHomes.SOFTWARE_HOME, 'foo')
        self.assertEqual(__builtin__.SOFTWARE_HOME, 'foo')
        self.assertEqual(Globals.SOFTWARE_HOME, 'foo')

    def testZopeHomeLegacySources(self):
        self.setconfig(zopehome='foo')
        self.assertEqual(os.environ.get('ZOPE_HOME'), 'foo')
        self.assertEqual(App.FindHomes.ZOPE_HOME, 'foo')
        self.assertEqual(__builtin__.ZOPE_HOME, 'foo')
        self.assertEqual(Globals.ZOPE_HOME, 'foo')

    def testDebugModeLegacySources(self):
        self.setconfig(debug_mode=True)
        self.assertEqual(Globals.DevelopmentMode, True)
        self.setconfig(debug_mode=False)
        self.assertEqual(Globals.DevelopmentMode, False)


def test_suite():
    suite = unittest.TestSuite()
    suite.addTest(unittest.makeSuite(SetConfigTests))
    return suite

if __name__ == '__main__':
    unittest.main(defaultTest='test_suite')
Zope-2.9.4-retire_zpkg/lib/python/App/tests/test_cachemanager.py0000644000175000017500000000464010337373524024665 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2003 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Tests for the CacheManager.

$Id: test_cachemanager.py 40222 2005-11-18 15:46:28Z andreasjung $
"""

import unittest

import ZODB

from App.CacheManager import CacheManager


class TestCacheManager(CacheManager):
    # Derived CacheManager that fakes enough of the DatabaseManager to
    # make it possible to test at least some parts of the CacheManager.

    def __init__(self, connection):
        self._p_jar = connection


class DummyConnection:

    def __init__(self, db, version=None):
        self.__db = db
        self.__version = version

    def db(self):
        return self.__db

    def getVersion(self):
        return self.__version


class DummyDB:

    def __init__(self, cache_size, vcache_size):
        self._set_sizes(cache_size, vcache_size)

    def _set_sizes(self, cache_size, vcache_size):
        self.__cache_size = cache_size
        self.__vcache_size = vcache_size

    def getCacheSize(self):
        return self.__cache_size

    def getVersionCacheSize(self):
        return self.__vcache_size


class CacheManagerTestCase(unittest.TestCase):

    def setUp(self):
        self.db = DummyDB(42, 24)
        self.connection = DummyConnection(self.db)
        self.manager = TestCacheManager(self.connection)

    def test_cache_size(self):
        self.assertEqual(self.manager.cache_size(), 42)
        self.db._set_sizes(12, 2)
        self.assertEqual(self.manager.cache_size(), 12)

    def test_version_cache_size(self):
        self.connection = DummyConnection(self.db, "my version")
        self.manager = TestCacheManager(self.connection)
        # perform test
        self.assertEqual(self.manager.cache_size(), 24)
        self.db._set_sizes(12, 2)
        self.assertEqual(self.manager.cache_size(), 2)


def test_suite():
    return unittest.makeSuite(CacheManagerTestCase)
Zope-2.9.4-retire_zpkg/lib/python/App/tests/testManagement.py0000644000175000017500000000072110247566145024203 0ustar  tseavertseaverimport unittest


class TestNavigation(unittest.TestCase):

    def test_z3interfaces(self):
        from App.interfaces import INavigation
        from App.Management import Navigation
        from zope.interface.verify import verifyClass

        verifyClass(INavigation, Navigation)


def test_suite():
    return unittest.TestSuite((
        unittest.makeSuite(TestNavigation),
        ))

if __name__ == '__main__':
    unittest.main(defaultTest='test_suite')
Zope-2.9.4-retire_zpkg/lib/python/App/tests/test_version_txt.py0000644000175000017500000000363110345323575024652 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2003 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Tests of the version number extraction.

$Id: test_version_txt.py 40592 2005-12-06 15:00:13Z philikon $
"""
import os
import unittest
import Zope2
import App.version_txt

class VersionTextTestCase(unittest.TestCase):

    def setUp(self):
        self.fn = os.path.join(os.path.dirname(Zope2.__file__), "version.txt")
        App.version_txt._test_reset()

    def tearDown(self):
        try:
            os.unlink(self.fn)
        except OSError:
            pass

    def writeVersion(self, s):
        f = open(self.fn, 'w')
        f.write(s)
        f.close()

    def test_without_version_txt(self):
        self.assertEqual(App.version_txt.getZopeVersion(),
                         (-1, -1, -1, '', -1))

    def test_with_version_txt_final(self):
        self.writeVersion("Zope 2.6.1 (source release, python 2.1, linux2)")
        self.assertEqual(App.version_txt.getZopeVersion(),
                         (2, 6, 1, '', -1))

    def test_with_version_txt_beta(self):
        self.writeVersion("Zope 2.6.1b2 (source release, python 2.1, linux2)")
        self.assertEqual(App.version_txt.getZopeVersion(),
                         (2, 6, 1, 'b', 2))


def test_suite():
    return unittest.makeSuite(VersionTextTestCase)

if __name__ == "__main__":
    unittest.main(defaultTest="test_suite")
Zope-2.9.4-retire_zpkg/lib/python/App/tests/__init__.py0000644000175000017500000000005010050234363022743 0ustar  tseavertseaver# Needed to make this a Python package.
Zope-2.9.4-retire_zpkg/lib/python/App/tests/testUndo.py0000644000175000017500000000072110247566145023034 0ustar  tseavertseaverimport unittest


class TestUndoSupport(unittest.TestCase):

    def test_z3interfaces(self):
        from App.interfaces import IUndoSupport
        from App.Undo import UndoSupport
        from zope.interface.verify import verifyClass

        verifyClass(IUndoSupport, UndoSupport)


def test_suite():
    return unittest.TestSuite((
        unittest.makeSuite(TestUndoSupport),
        ))

if __name__ == '__main__':
    unittest.main(defaultTest='test_suite')
Zope-2.9.4-retire_zpkg/lib/python/App/tests/testPersistentExtra.py0000644000175000017500000000153510247566145025277 0ustar  tseavertseaverimport unittest
import Testing
import Zope2
Zope2.startup()


class TestPersistentUtil(unittest.TestCase):

    def test_z3interfaces(self):
        from App.interfaces import IPersistentExtra
        from App.PersistentExtra import PersistentUtil
        from zope.interface.verify import verifyClass

        verifyClass(IPersistentExtra, PersistentUtil)


class TestPersistent(unittest.TestCase):

    def test_z3interfaces(self):
        from App.interfaces import IPersistentExtra
        from Persistence import Persistent
        from zope.interface.verify import verifyClass

        verifyClass(IPersistentExtra, Persistent)


def test_suite():
    return unittest.TestSuite((
        unittest.makeSuite(TestPersistentUtil),
        unittest.makeSuite(TestPersistent),
        ))

if __name__ == '__main__':
    unittest.main(defaultTest='test_suite')
Zope-2.9.4-retire_zpkg/lib/python/App/tests/test_class_init.py0000644000175000017500000000243610337373524024420 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2005 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Tests class initialization.
"""

import ExtensionClass
from App.class_init import default__class_init__ as InitializeClass


def test_InitializeClass():
    """Test that InitializeClass (default__class_init__)
    works in specific corner cases.

    Check when the class has an ExtensionClass as attribute.

    >>> class AnotherClass(ExtensionClass.Base):
    ...     _need__name__ = 1

    >>> class C:
    ...     foo = AnotherClass

    >>> InitializeClass(C)
    """

from zope.testing.doctest import DocTestSuite
import unittest

def test_suite():
    return unittest.TestSuite((
        DocTestSuite(),
        ))

if __name__ == '__main__':
    unittest.main()
Zope-2.9.4-retire_zpkg/lib/python/App/CacheManager.py0000644000175000017500000002342110337373524022362 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
'''Cache management support.

This class is mixed into the database manager in App.ApplicationManager.

$Id: CacheManager.py 40222 2005-11-18 15:46:28Z andreasjung $'''
__version__='$Revision: 1.31 $'[11:-2]

import time

import Globals
from DateTime import DateTime

class CacheManager:
    """Cache management mix-in
    """
    _cache_age = 60
    _vcache_age = 60
    _history_length = 3600  # Seconds

    manage_cacheParameters = Globals.DTMLFile('dtml/cacheParameters',
                                              globals())
    manage_cacheGC = Globals.DTMLFile('dtml/cacheGC', globals())

    transparent_bar = Globals.ImageFile('www/transparent_bar.gif', globals())
    store_bar = Globals.ImageFile('www/store_bar.gif', globals())
    load_bar = Globals.ImageFile('www/load_bar.gif', globals())

    def _getDB(self):
        return self._p_jar.db()

    def _inVersion(self):
        return self._p_jar.getVersion() and True or False

    def cache_length(self):
        return self._getDB().cacheSize()

    def cache_detail_length(self):
        return self._getDB().cacheDetailSize()

    def database_size(self):
        return self._getDB().objectCount()

    def cache_age(self):
        if self._inVersion():
            return self._vcache_age
        else:
            return self._cache_age

    def manage_cache_age(self,value,REQUEST):
        "set cache age"
        db = self._getDB()
        if self._inVersion():
            self._vcache_age = value
            db.setVersionCacheDeactivateAfter(value)
        else:
            self._cache_age = value
            db.setCacheDeactivateAfter(value)

        if REQUEST is not None:
            response=REQUEST['RESPONSE']
            response.redirect(REQUEST['URL1']+'/manage_cacheParameters')

    def cache_size(self):
        db = self._getDB()
        if self._inVersion():
            return db.getVersionCacheSize()
        else:
            return db.getCacheSize()

    def manage_cache_size(self,value,REQUEST):
        "set cache size"
        db = self._getDB()
        if self._inVersion():
            db.setVersionCacheSize(value)
        else:
            db.setCacheSize(value)

        if REQUEST is not None:
            response=REQUEST['RESPONSE']
            response.redirect(REQUEST['URL1']+'/manage_cacheParameters')


    # BoboPOS 2
    def cache_mean_age(self):
        return Globals.Bobobase._jar.cache.cache_mean_age/60.0

    # BoboPOS 2
    def cache_mean_deal(self):
        return Globals.Bobobase._jar.cache.cache_mean_deal*60

    # BoboPOS 2
    def cache_mean_deac(self):
        return Globals.Bobobase._jar.cache.cache_mean_deac*60

    # BoboPOS 2
    def cache_last_gc_time(self):
        t=Globals.Bobobase._jar.cache.cache_last_gc_time
        return time.asctime(time.localtime(t))

    def manage_full_sweep(self,value,REQUEST):
        "Perform a full sweep through the cache"
        db = self._getDB()
        db.cacheFullSweep(value)

        if REQUEST is not None:
            response=REQUEST['RESPONSE']
            response.redirect(REQUEST['URL1']+'/manage_cacheGC')

    def manage_minimize(self,value=1,REQUEST=None):
        "Perform a full sweep through the cache"
        # XXX Add a deprecation warning about value?
        self._getDB().cacheMinimize()

        if REQUEST is not None:
            response=REQUEST['RESPONSE']
            response.redirect(REQUEST['URL1']+'/manage_cacheGC')

    def cache_detail(self, REQUEST=None):
        """
        Returns the name of the classes of the objects in the cache
        and the number of objects in the cache for each class.
        """
        detail = self._getDB().cacheDetail()
        if REQUEST is not None:
            # format as text
            REQUEST.RESPONSE.setHeader('Content-Type', 'text/plain')
            return '\n'.join(map(lambda (name, count): '%6d %s' %
                                   (count, name), detail))
        else:
            # raw
            return detail

    def cache_extreme_detail(self, REQUEST=None):
        """
        Returns information about each object in the cache.
        """
        detail = self._getDB().cacheExtremeDetail()
        if REQUEST is not None:
            # sort the list.
            lst = map(lambda dict: ((dict['conn_no'], dict['oid']), dict),
                      detail)
            # format as text.
            res = [
                '# Table shows connection number, oid, refcount, state, '
                'and class.',
                '# States: L = loaded, G = ghost, C = changed']
            for sortkey, dict in lst:
                id = dict.get('id', None)
                if id:
                    idinfo = ' (%s)' % id
                else:
                    idinfo = ''
                s = dict['state']
                if s == 0:
                    state = 'L'  # loaded
                elif s == 1:
                    state = 'C'  # changed
                else:
                    state = 'G'  # ghost
                res.append('%d %-34s %6d %s %s%s' % (
                    dict['conn_no'], `dict['oid']`, dict['rc'],
                    state, dict['klass'], idinfo))
            REQUEST.RESPONSE.setHeader('Content-Type', 'text/plain')
            return '\n'.join(res)
        else:
            # raw
            return detail

    def _getActivityMonitor(self):
        db = self._getDB()
        if not hasattr(db, 'getActivityMonitor'):
            return None
        am = db.getActivityMonitor()
        if am is None:
            return None
        return am

    def getHistoryLength(self):
        am = self._getActivityMonitor()
        if am is None:
            return 0
        return am.getHistoryLength()

    def manage_setHistoryLength(self, length, REQUEST=None):
        """Change the length of the activity monitor history.
        """
        am = self._getActivityMonitor()
        length = int(length)
        if length < 0:
            raise ValueError, 'length can not be negative'
        if am is not None:
            am.setHistoryLength(length)
        self._history_length = length  # Restore on startup

        if REQUEST is not None:
            response = REQUEST['RESPONSE']
            response.redirect(REQUEST['URL1'] + '/manage_activity')

    def getActivityChartData(self, segment_height, REQUEST=None):
        """Returns information for generating an activity chart.
        """
        am = self._getActivityMonitor()
        if am is None:
            return None

        if REQUEST is not None:
            start = float(REQUEST.get('chart_start', 0))
            end = float(REQUEST.get('chart_end', 0))
            divisions = int(REQUEST.get('chart_divisions', 10))
            analysis = am.getActivityAnalysis(start, end, divisions)
        else:
            analysis = am.getActivityAnalysis()

        total_load_count = 0
        total_store_count = 0
        total_connections = 0
        limit = 0
        divs = []
        for div in analysis:
            total_store_count = total_store_count + div['stores']
            total_load_count = total_load_count + div['loads']
            total_connections = total_connections + div['connections']
            sum = div['stores'] + div['loads']
            if sum > limit:
                limit = sum

        if analysis:
            segment_time = analysis[0]['end'] - analysis[0]['start']
        else:
            segment_time = 0

        for div in analysis:
            stores = div['stores']
            if stores > 0:
                store_len = max(int(segment_height * stores / limit), 1)
            else:
                store_len = 0
            loads = div['loads']
            if loads > 0:
                load_len = max(int(segment_height * loads / limit), 1)
            else:
                load_len = 0

            t = div['end'] - analysis[-1]['end']  # Show negative numbers.
            if segment_time >= 3600:
                # Show hours.
                time_offset = '%dh' % (t / 3600)
            elif segment_time >= 60:
                # Show minutes.
                time_offset = '%dm' % (t / 60)
            elif segment_time >= 1:
                # Show seconds.
                time_offset = '%ds' % t
            else:
                # Show fractions.
                time_offset = '%.2fs' % t
            divs.append({
                'store_len': store_len,
                'load_len': load_len,
                'trans_len': max(segment_height - store_len - load_len, 0),
                'store_count': div['stores'],
                'load_count': div['loads'],
                'connections': div['connections'],
                'start': div['start'],
                'end': div['end'],
                'time_offset': time_offset,
                })

        if analysis:
            start_time = DateTime(divs[0]['start']).aCommonZ()
            end_time = DateTime(divs[-1]['end']).aCommonZ()
        else:
            start_time = ''
            end_time = ''

        res = {'start_time': start_time,
               'end_time': end_time,
               'divs': divs,
               'total_store_count': total_store_count,
               'total_load_count': total_load_count,
               'total_connections': total_connections,
               }
        return res


Globals.default__class_init__(CacheManager)
Zope-2.9.4-retire_zpkg/lib/python/App/special_dtml.py0000644000175000017500000001607510337373524022533 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

import DocumentTemplate, Common, Persistence, MethodObject, Globals, os, sys
from types import InstanceType
from zLOG import LOG,WARNING
from App.config import getConfiguration

class HTML(DocumentTemplate.HTML,Persistence.Persistent,):
    "Persistent HTML Document Templates"

class ClassicHTMLFile(DocumentTemplate.HTMLFile,MethodObject.Method,):
    "Persistent HTML Document Templates read from files"

    class func_code: pass
    func_code=func_code()
    func_code.co_varnames='trueself', 'self', 'REQUEST'
    func_code.co_argcount=3
    _need__name__=1
    _v_last_read=0

    def __init__(self,name,_prefix=None, **kw):
        if _prefix is None: _prefix=getConfiguration().softwarehome
        elif type(_prefix) is not type(''):
            _prefix=Common.package_home(_prefix)
        args=(self, os.path.join(_prefix, name + '.dtml'))
        if not kw.has_key('__name__'):
            kw['__name__']=os.path.split(name)[-1]
        apply(ClassicHTMLFile.inheritedAttribute('__init__'),args,kw)

    def _cook_check(self):
        if Globals.DevelopmentMode:
            __traceback_info__=self.raw
            try:    mtime=os.stat(self.raw)[8]
            except: mtime=0
            if mtime != self._v_last_read:
                self.cook()
                self._v_last_read=mtime
        elif not hasattr(self,'_v_cooked'):
            try: changed=self.__changed__()
            except: changed=1
            self.cook()
            if not changed: self.__changed__(0)

    def _setName(self, name):
        self.__name__ = name
        self._need__name__ = 0

    def __call__(self, *args, **kw):
        self._cook_check()
        return apply(HTMLFile.inheritedAttribute('__call__'),
                     (self,)+args[1:],kw)

defaultBindings = {'name_context': 'context',
                   'name_container': 'container',
                   'name_m_self': 'self',
                   'name_ns': 'caller_namespace',
                   'name_subpath': 'traverse_subpath'}

from Shared.DC.Scripts.Bindings import Bindings
from Acquisition import Explicit, aq_inner, aq_parent
from DocumentTemplate.DT_String import _marker, DTReturn, render_blocks
from DocumentTemplate.DT_Util import TemplateDict, InstanceDict
from AccessControl import getSecurityManager
from ComputedAttribute import ComputedAttribute

class DTMLFile(Bindings, Explicit, ClassicHTMLFile):
    "HTMLFile with bindings and support for __render_with_namespace__"

    func_code = None
    func_defaults = None
    _need__name__=1

    _Bindings_ns_class = TemplateDict
    def _get__roles__(self):
        imp = getattr(aq_parent(aq_inner(self)),
                      '%s__roles__' % self.__name__)
        if hasattr(imp, '__of__'):
            return imp.__of__(self)
        return imp

    __roles__ = ComputedAttribute(_get__roles__, 1)

    # By default, we want to look up names in our container.
    _Bindings_client = 'container'

    def __init__(self, name, _prefix=None, **kw):

        self.ZBindings_edit(defaultBindings)
        self._setFuncSignature()
        apply(DTMLFile.inheritedAttribute('__init__'),
              (self, name, _prefix), kw)

    def getOwner(self, info=0):
        '''
        This method is required of all objects that go into
        the security context stack.
        '''
        return None

    def _exec(self, bound_data, args, kw):
        # Cook if we haven't already
        self._cook_check()

        # Get our caller's namespace, and set up our own.
        cns = bound_data['caller_namespace']
        ns = self._Bindings_ns_class()
        push = ns._push
        ns.guarded_getattr = None
        ns.guarded_getitem = None

        req = None
        kw_bind = kw
        if cns:
            # Someone called us.
            push(cns)
            ns.level = cns.level + 1
            ns.this = getattr(cns, 'this', None)
            # Get their bindings.  Copy the request reference
            # forward, and include older keyword arguments in the
            # current 'keyword_args' binding.
            try:
                last_bound = ns[('current bindings',)]
                last_req = last_bound.get('REQUEST', None)
                if last_req:
                    bound_data['REQUEST'] = last_req
                old_kw = last_bound['keyword_args']
                if old_kw:
                    kw_bind = old_kw.copy()
                    kw_bind.update(kw)
            except: pass
        else:
            # We're first, so get the REQUEST.
            try:
                req = self.aq_acquire('REQUEST')
                if hasattr(req, 'taintWrapper'):
                    req = req.taintWrapper()
            except: pass
            bound_data['REQUEST'] = req
            ns.this = bound_data['context']
        # Bind 'keyword_args' to the complete set of keyword arguments.
        bound_data['keyword_args'] = kw_bind

        # Push globals, initialized variables, REQUEST (if any),
        # and keyword arguments onto the namespace stack

        for nsitem in (self.globals, self._vars, req, kw):
            if nsitem:
                push(nsitem)

        # Push the 'container' (default), 'context', or nothing.
        bind_to = self._Bindings_client
        if bind_to in ('container', 'client'):
            push(InstanceDict(bound_data[bind_to], ns))

        # Push the name bindings, and a reference to grab later.
        push(bound_data)
        push({('current bindings',): bound_data})

        security = getSecurityManager()
        security.addContext(self)
        try:
            value = self.ZDocumentTemplate_beforeRender(ns, _marker)
            if value is _marker:
                try: result = render_blocks(self._v_blocks, ns)
                except DTReturn, v: result = v.v
                except AttributeError:
                    if type(sys.exc_value)==InstanceType and sys.exc_value.args[0]=="_v_blocks":
                        LOG("ZPublisher",WARNING,"DTML file '%s' could not be read" % self.raw)
                        raise ValueError, ("DTML file error: "
                                           "Check logfile for details")
                    else:
                        raise

                self.ZDocumentTemplate_afterRender(ns, result)
                return result
            else:
                return value
        finally:
            security.removeContext(self)
            # Clear the namespace, breaking circular references.
            while len(ns): ns._pop()
    from Shared.DC.Scripts.Signature import _setFuncSignature


HTMLFile = ClassicHTMLFile
Zope-2.9.4-retire_zpkg/lib/python/App/Extensions.py0000644000175000017500000001331110337373524022220 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
__doc__='''Standard routines for handling extensions.

Extensions currently include external methods and pluggable brains.

$Id: Extensions.py 40222 2005-11-18 15:46:28Z andreasjung $'''
__version__='$Revision: 1.23 $'[11:-2]

import os, zlib, imp
import Products
from zExceptions import NotFound
path_split=os.path.split
path_join=os.path.join
exists=os.path.exists

class FuncCode:

    def __init__(self, f, im=0):
        self.co_varnames=f.func_code.co_varnames[im:]
        self.co_argcount=f.func_code.co_argcount-im

    def __cmp__(self,other):
        if other is None: return 1
        try: return cmp((self.co_argcount, self.co_varnames),
                        (other.co_argcount, other.co_varnames))
        except: return 1


def _getPath(home, prefix, name, suffixes):
    d=path_join(home, prefix)
    if d==prefix: raise ValueError, (
        'The prefix, %s, should be a relative path' % prefix)
    d=path_join(d,name)
    if d==name: raise ValueError, ( # Paranoia
        'The file name, %s, should be a simple file name' % name)
    for s in suffixes:
        if s: s="%s.%s" % (d, s)
        else: s=d
        if exists(s): return s

def getPath(prefix, name, checkProduct=1, suffixes=('',)):
    """Find a file in one of several relative locations

    Arguments:

      prefix -- The location, relative to some home, to look for the
                file

      name -- The name of the file.  This must not be a path.

      checkProduct -- a flag indicating whether product directories
        should be used as additional hope ares to be searched. This
        defaults to a true value.

        If this is true and the name contains a dot, then the
        text before the dot is treated as a product name and
        the product package directory is used as anothe rhome.

      suffixes -- a sequences of file suffixes to check.
        By default, the name is used without a suffix.

    The search takes on multiple homes which are the instance home,
    the directory containing the directory containing the software
    home, and possibly product areas.
    """
    d,n = path_split(name)
    if d: raise ValueError, (
        'The file name, %s, should be a simple file name' % name)

    if checkProduct:
        l = name.find('.')
        if l > 0:
            p = name[:l]
            n = name[l + 1:]
            for product_dir in Products.__path__:
                r = _getPath(product_dir, os.path.join(p, prefix), n, suffixes)
                if r is not None: return r

    import App.config
    cfg = App.config.getConfiguration()
    sw=os.path.dirname(os.path.dirname(cfg.softwarehome))
    for home in (cfg.instancehome, sw):
        r=_getPath(home, prefix, name, suffixes)
        if r is not None: return r

def getObject(module, name, reload=0,
              # The use of a mutable default is intentional here,
              # because modules is a module cache.
              modules={}
              ):

    # The use of modules here is not thread safe, however, there is
    # no real harm in a race condition here.  If two threads
    # update the cache, then one will have simply worked a little
    # harder than need be.  So, in this case, we won't incur
    # the expense of a lock.
    old = modules.get(module)
    if old is not None and name in old and not reload:
        return old[name]

    base, ext = os.path.splitext(module)
    if ext in ('py', 'pyp', 'pyc'):
        # XXX should never happen; splitext() keeps '.' with the extension
        p = base
    else:
        p = module
    p=getPath('Extensions', p, suffixes=('','py','pyp','pyc'))
    if p is None:
        raise NotFound, (
            "The specified module, %s, couldn't be found." % module)

    __traceback_info__=p, module

    base, ext = os.path.splitext(p)
    if ext=='.pyc':
        file = open(p, 'rb')
        binmod=imp.load_compiled('Extension', p, file)
        file.close()
        m=binmod.__dict__

    elif ext=='.pyp':
        import rotor
        prod_id=module.split('.', 1)[0]
        data=zlib.decompress(
            rotor.newrotor(prod_id +' shshsh').decrypt(open(p,'rb').read())
            )
        execsrc=compile(data, module, 'exec')
        m={}
        exec execsrc in m

    else:
        try: execsrc=open(p)
        except: raise NotFound, (
            "The specified module, %s, couldn't be opened."
            % module)
        m={}
        exec execsrc in m

    if old is not None:
        old.update(m)
    else:
        modules[module] = m

    try:
        return m[name]
    except KeyError:
        raise NotFound, (
            "The specified object, %s, was not found in module, "
            "%s." % (name, module))

class NoBrains: pass

def getBrain(module, class_name, reload=0):
    'Check/load a class'

    if not module and not class_name: return NoBrains

    try: c=getObject(module, class_name, reload)
    except KeyError, v:
        if v == class_name: raise ValueError, (
            'The class, %s, is not defined in file, %s' % (class_name, module))

    if not hasattr(c,'__bases__'): raise ValueError, (
        '%s, is not a class' % class_name)

    return c
Zope-2.9.4-retire_zpkg/lib/python/App/__init__.py0000644000175000017500000000117210337373524021622 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
Zope-2.9.4-retire_zpkg/lib/python/App/PersistentExtra.py0000644000175000017500000000521110337373524023225 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Patch for Persistent to support IPersistentExtra.

$Id: PersistentExtra.py 40222 2005-11-18 15:46:28Z andreasjung $
"""

import Globals
from DateTime import DateTime
from Persistence import Persistent
from zope.interface import classImplements
from zope.interface import implements

from class_init import default__class_init__
from interfaces import IPersistentExtra


Persistent.__class_init__ = default__class_init__

class PersistentUtil:

    implements(IPersistentExtra)

    def bobobase_modification_time(self):
        jar=self._p_jar
        oid=self._p_oid
        if jar is None or oid is None: return DateTime()

        try:
            t=self._p_mtime
            if t is None: return DateTime()
        except: t=0
        return DateTime(t)

    def locked_in_version(self):
        """Was the object modified in any version?
        """
        jar=self._p_jar
        oid=self._p_oid
        if jar is None or oid is None: return None
        try: mv=jar.modifiedInVersion
        except: pass
        else: return mv(oid)

        # BoboPOS 2 code:
        oid=self._p_oid
        return (oid
                and Globals.VersionBase.locks.has_key(oid)
                and Globals.VersionBase.verify_lock(oid)
                and 'some version')

    def modified_in_version(self):
        """Was the object modified in this version?
        """
        jar=self._p_jar
        oid=self._p_oid
        if jar is None or oid is None: return None
        try: mv=jar.modifiedInVersion
        except: pass
        else: return mv(oid)==jar.getVersion()

        # BoboPOS 2 code:
        jar=self._p_jar
        if jar is None:
            if hasattr(self,'aq_parent') and hasattr(self.aq_parent, '_p_jar'):
                jar=self.aq_parent._p_jar
            if jar is None: return 0
        if not jar.name: return 0
        try: jar.db[self._p_oid]
        except: return 0
        return 1

for k, v in PersistentUtil.__dict__.items():
    if k[0] != '_':
        setattr(Persistent, k, v)

classImplements(Persistent, IPersistentExtra)
Zope-2.9.4-retire_zpkg/lib/python/App/config.py0000644000175000017500000000702710337373524021335 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2003 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################

"""Simple access to configuration values.

The configuration values are represented as a single object with
attributes for each bit of information.
"""

import sys

_config = None

def getConfiguration():
    """Return the global Zope configuration object.

    If a configuration hasn't been set yet, generates a simple
    configuration object and uses that.  Once generated, it may not be
    overridden by calling ``setConfiguration()``.
    """
    if _config is None:
        setConfiguration(DefaultConfiguration())
    return _config

def setConfiguration(cfg):
    """Set the global configuration object.

    Legacy sources of common configuraiton values are updated to
    reflect the new configuration; this may be removed in some future
    version.
    """
    global _config
    _config = cfg

    if cfg is None:
        return

    from App import FindHomes
    import __builtin__
    __builtin__.CLIENT_HOME = FindHomes.CLIENT_HOME = cfg.clienthome
    __builtin__.INSTANCE_HOME = FindHomes.INSTANCE_HOME = cfg.instancehome
    __builtin__.SOFTWARE_HOME = FindHomes.SOFTWARE_HOME = cfg.softwarehome
    __builtin__.ZOPE_HOME = FindHomes.ZOPE_HOME = cfg.zopehome

    # XXX make sure the environment variables, if set, don't get out
    # of sync.  This is needed to support 3rd-party code written to
    # support Zope versions prior to 2.7.
    import os
    os.environ["CLIENT_HOME"] = cfg.clienthome
    os.environ["INSTANCE_HOME"] = cfg.instancehome
    os.environ["SOFTWARE_HOME"] = cfg.softwarehome
    os.environ["ZOPE_HOME"] = cfg.zopehome

    if "Globals" in sys.modules:
        # XXX We *really* want to avoid this if Globals hasn't already
        # been imported, due to circular imports.  ;-(
        import Globals
        Globals.data_dir = cfg.clienthome
        # Globals does not export CLIENT_HOME
        Globals.INSTANCE_HOME = cfg.instancehome
        Globals.SOFTWARE_HOME = cfg.softwarehome
        Globals.ZOPE_HOME = cfg.zopehome
        Globals.DevelopmentMode = cfg.debug_mode

class DefaultConfiguration:
    """
    This configuration should be used effectively only during unit tests
    """
    def __init__(self):
        from App import FindHomes
        self.clienthome = FindHomes.CLIENT_HOME
        self.instancehome = FindHomes.INSTANCE_HOME
        self.softwarehome = FindHomes.SOFTWARE_HOME
        self.zopehome = FindHomes.ZOPE_HOME
        self.dbtab = None
        self.debug_mode = True
        self.enable_product_installation = True
        self.locale = None

        # restructured text
        default_enc = sys.getdefaultencoding()
        self.rest_input_encoding = default_enc
        self.rest_output_encoding = default_enc
        self.rest_header_level = 3
        self.rest_language_code = 'en'

        # ZServer.HTTPServer
        self.http_header_max_length = 8196

        # VerboseSecurity
        self.skip_ownership_checking = False
        self.skip_authentication_checking = False
Zope-2.9.4-retire_zpkg/lib/python/App/Factory.py0000644000175000017500000000754110337373524021500 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
__doc__='''Factory objects

$Id: Factory.py 40222 2005-11-18 15:46:28Z andreasjung $'''
__version__='$Revision: 1.27 $'[11:-2]

import OFS.SimpleItem, Acquisition, Globals, AccessControl.Role

class Factory(
    AccessControl.Role.RoleManager,
    Globals.Persistent, Acquisition.Implicit, OFS.SimpleItem.Item
    ):
    "Model factory meta-data"
    meta_type='Zope Factory'
    icon='p_/Factory_icon'

    permission='' # Waaaa

    _setObject=_getOb=Acquisition.Acquired

    __ac_permissions__=(
        ('Edit Factories', ('manage_edit','manage_main')),
        ('Use Factories', ('index_html','')),
        )

    manage_options=(
        (
        {'label':'Edit', 'action':'manage_main',
         'help':('OFSP','Zope-Factory_Edit.stx')},
        )
        +AccessControl.Role.RoleManager.manage_options
        +OFS.SimpleItem.Item.manage_options
        )

    def __init__(self, id, title, object_type, initial, permission=''):
        self.id=id
        self.title=title
        self.object_type=object_type
        self.initial=initial
        self.permission=permission

    initializePermission__roles__ = ()
    def initializePermission(self):
        self.manage_setPermissionMapping(('Use Factories',),
                                         (self.permission,))

    def manage_edit(self, title, object_type, initial, permission='',
                    REQUEST=None):
        "Modify factory properties."
        self._unregister()
        self.title=title
        self.object_type=object_type
        self.initial=initial
        self.permission=permission
        self.manage_setPermissionMapping(('Use Factories',), (permission,))
        self._register()
        if REQUEST is not None: return self.manage_main(self, REQUEST)

    def manage_afterAdd(self, item, container):
        import Product  # local to avoid circular import
        if hasattr(self, 'aq_parent'):
            container=self.aq_parent
        elif item is not self:
            container=None
        if (item is self or
            getattr(container, '__class__', None) is Product.Product):
            self._register()

    def manage_beforeDelete(self, item, container):
        import Product  # local to avoid circular import
        if hasattr(self, 'aq_parent'):
            container=self.aq_parent
        elif item is not self:
            container=None

        if (item is self or
            getattr(container, '__class__', None) is Product.Product):
            self._unregister()

    def _register(self):
        # Register with the product folder
        product=self.aq_parent
        product.aq_acquire('_manage_add_product_meta_type')(
            product, self.id, self.object_type, self.permission)

    def _unregister(self):
        # Unregister with the product folder
        product=self.aq_parent
        product.aq_acquire('_manage_remove_product_meta_type')(
            product, self.id, self.object_type)

    manage_main=Globals.DTMLFile('dtml/editFactory',globals())

    def index_html(self, REQUEST):
        " "
        return getattr(self, self.initial)(self.aq_parent, REQUEST)

    def objectIds(self):
        return filter(
            lambda id, myid=self.id: id != myid,
            self.aq_parent.objectIds()
            )

class ProductFactory(Factory): pass
Zope-2.9.4-retire_zpkg/lib/python/App/ProductRegistry.py0000644000175000017500000001445410337373524023243 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

# Product registry and new product factory model.  There will be a new
# mechanism for defining actions for meta types.  If an action is of
# the form:
#
#  manage_addProduct-name-factoryid
#
# Then the machinery that invokes an add-product form
# will return:
# ....what?

from OFS.Folder import Folder

class ProductRegistryMixin:
    # This class implements a protocol for registering products that
    # are defined through the web.

    # This class is a mix-in class for the top-level application object.

    def _manage_remove_product_meta_type(self, product,
                                         id=None, meta_type=None):
        r=[]
        pid=product.id
        for mt in self._getProductRegistryMetaTypes():
            if mt.has_key('product'):
                if mt['product']==pid and (
                    meta_type is None or meta_type==mt['name']):
                    continue
                elif meta_type==mt['name']: continue
                r.append(mt)

        self._setProductRegistryMetaTypes(tuple(r))

    def _constructor_prefix_string(self, pid):
        return 'manage_addProduct/%s/' % pid

    def _manage_add_product_meta_type(self, product, id, meta_type,
                                      permission=''):
        pid=product.id

        meta_types=self._getProductRegistryMetaTypes()

        for mt in meta_types:
            if mt['name']==meta_type:
                if not mt.has_key('product'): mt['product']=pid
                if mt['product'] != pid:
                    raise ValueError, (
                        'The type %s is already defined.' % meta_type)
                mt['action']='%s%s' % (
                    self._constructor_prefix_string(pid), id)
                if permission: mt['permission']=permission
                return

        mt={
            'name': meta_type,
            'action': ('%s%s' % (
                self._constructor_prefix_string(pid), id)),
            'product': pid
            }
        if permission: mt['permission']=permission

        self._setProductRegistryMetaTypes(meta_types+(mt,))

    def _manage_remove_product_permission(self, product, permission=None):
        r=[]
        r2=[]
        pid=product.id
        for d in self._getProductRegistryData('permissions'):
            if d.has_key('product'):
                if d['product']==pid and (
                    permission is None or permission==d['name']):
                    continue
                elif permission==d['name']: continue
                r.append(d)
                r2.append((d['name'], d['methods'], d['default']))

        self._setProductRegistryData('permissions', tuple(r))
        self._setProductRegistryData('ac_permissions', tuple(r2))

    def _manage_add_product_permission(
        self, product, permission, methods=(), default=('Manager',)
        ):

        permissions=self._getProductRegistryData('permissions')

        for d in permissions:
            if d['name']==permission:
                raise ValueError, (
                    'The permission %s is already defined.'
                    % permission)

        d={'name': permission, 'methods': methods, 'permission': permission,
                'default': default, 'product': product.id}

        self._setProductRegistryData('permissions', permissions + (d,))
        self._setProductRegistryData(
            'ac_permissions',
            self._getProductRegistryData('ac_permissions')
            +((d['name'], d['methods'], d['default']),)
            )

    # HACK - sometimes an unwrapped App object seems to be passed as
    # self to these methods, which means that they dont have an aq_aquire
    # method. Until Jim has time to look into this, this aq_maybe method
    # appears to be an effective work-around...
    def aq_maybe(self, name):
        if hasattr(self, name):
            return getattr(self, name)
        return self.aq_acquire(name)

    def _manage_add_product_data(self, type, product, id, **data):
        values=filter(
            lambda d, product=product, id=id:
            not (d['product']==product and d['id']==id),
            list(self.aq_maybe('_getProductRegistryData')(type))
            )

        data['product']=product
        data['id']=id
        values.append(data)

        self.aq_maybe('_setProductRegistryData')(type, tuple(values))

    def _manage_remove_product_data(self, type, product, id):
        values=filter(
            lambda d, product=product, id=id:
            not (d['product'] in
                 (product,
                  'methods' # hack to get around inner ZClass reg. bug
                  ) and d['id']==id),
            self.aq_maybe('_getProductRegistryData')(type)
            )

        self.aq_maybe('_setProductRegistryData')(type, tuple(values))



class ProductRegistry(ProductRegistryMixin):
    # This class implements a protocol for registering products that
    # are defined through the web.  It also provides methods for
    # getting hold of the Product Registry, Control_Panel.Products.

    # This class is a mix-in class for the top-level application object.

    def _getProducts(self): return self.Control_Panel.Products

    _product_meta_types=()
    _product_permissions=()
    _product_ac_permissions=()

    _product_zclasses=() # product, id, meta_type, class


    def _getProductRegistryMetaTypes(self): return self._product_meta_types
    def _setProductRegistryMetaTypes(self, v): self._product_meta_types=v

    def _getProductRegistryData(self, name):
        return getattr(self, '_product_%s' % name)

    def _setProductRegistryData(self, name, v):
        name='_product_%s' % name
        if hasattr(self, name):
            return setattr(self, name, v)
        else:
            raise AttributeError, name
Zope-2.9.4-retire_zpkg/lib/python/App/FactoryDispatcher.py0000644000175000017500000000670410337373524023507 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################


# Implement the manage_addProduct method of object managers
import Acquisition, sys, Products
from AccessControl.PermissionMapping import aqwrap
from AccessControl.Owned import UnownableOwner

class ProductDispatcher(Acquisition.Implicit):
    " "
    # Allow access to factory dispatchers
    __allow_access_to_unprotected_subobjects__=1

    def __getitem__(self, name):
        return self.__bobo_traverse__(None, name)

    def __bobo_traverse__(self, REQUEST, name):
        product=self.aq_acquire('_getProducts')()._product(name)

        # Try to get a custom dispatcher from a Python product
        dispatcher_class=getattr(
            getattr(Products, name, None),
            '__FactoryDispatcher__',
            FactoryDispatcher)

        dispatcher=dispatcher_class(product, self.aq_parent, REQUEST)
        return dispatcher.__of__(self)

class FactoryDispatcher(Acquisition.Implicit):
    """Provide a namespace for product "methods"
    """

    _owner=UnownableOwner

    def __init__(self, product, dest, REQUEST=None):
        if hasattr(product,'aq_base'): product=product.aq_base
        self._product=product
        self._d=dest
        if REQUEST is not None:
            try:
                v=REQUEST['URL']
            except KeyError: pass
            else:
                v=v[:v.rfind('/')]
                self._u=v[:v.rfind('/')]

    def Destination(self):
        "Return the destination for factory output"
        return self.__dict__['_d'] # we don't want to wrap the result!
    this=Destination
    this__roles__=Destination__roles__=None


    def DestinationURL(self):
        "Return the URL for the destination for factory output"
        url=getattr(self, '_u', None)
        if url is None:
            url=self.Destination().absolute_url()
        return url

    DestinationURL__roles__=None

    def __getattr__(self, name):
        p=self.__dict__['_product']
        d=p.__dict__
        if hasattr(p,name) and d.has_key(name):
            m=d[name]
            w=getattr(m, '_permissionMapper', None)
            if w is not None:
                m=aqwrap(m, getattr(w,'aq_base',w), self)

            return m

        # Waaa
        m='Products.%s' % p.id
        if sys.modules.has_key(m) and sys.modules[m]._m.has_key(name):
            return sys.modules[m]._m[name]

        raise AttributeError, name

    # Provide acquired indicators for critical OM methods:
    _setObject=_getOb=Acquisition.Acquired

    # Make sure factory methods are unowned:
    _owner=UnownableOwner

    # Provide a replacement for manage_main that does a redirection:
    def manage_main(trueself, self, REQUEST, update_menu=0):
        """Implement a contents view by redirecting to the true view
        """
        d = update_menu and '/manage_main?update_menu=1' or '/manage_main'
        REQUEST['RESPONSE'].redirect(self.DestinationURL()+d)

Zope-2.9.4-retire_zpkg/lib/python/App/Management.py0000644000175000017500000001555710337373524022153 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Standard management interface support

$Id: Management.py 40222 2005-11-18 15:46:28Z andreasjung $
"""

import sys, Globals, ExtensionClass, urllib
from Globals import DTMLFile, HTMLFile
from zExceptions import Redirect
from AccessControl import getSecurityManager, Unauthorized
from cgi import escape
from zope.interface import implements

from interfaces import INavigation


class Tabs(ExtensionClass.Base):
    """Mix-in provides management folder tab support."""

    manage_tabs__roles__=('Anonymous',)
    manage_tabs=DTMLFile('dtml/manage_tabs', globals())


    manage_options  =()

    filtered_manage_options__roles__=None
    def filtered_manage_options(self, REQUEST=None):

        validate=getSecurityManager().validate

        result=[]

        try:
            options=tuple(self.manage_options)
        except TypeError:
            options=tuple(self.manage_options())

        for d in options:

            filter=d.get('filter', None)
            if filter is not None and not filter(self):
                continue

            path=d.get('path', None)
            if path is None:
                    path=d['action']

            o=self.restrictedTraverse(path, None)
            if o is None:
                continue

            result.append(d)

        return result


    manage_workspace__roles__=('Authenticated',)
    def manage_workspace(self, REQUEST):
        """Dispatch to first interface in manage_options
        """
        options=self.filtered_manage_options(REQUEST)
        try:
            m=options[0]['action']
            if m=='manage_workspace':
                    raise TypeError
        except (IndexError, KeyError):
            raise Unauthorized, (
                'You are not authorized to view this object.')

        if m.find('/'):
            raise Redirect, (
                "%s/%s" % (REQUEST['URL1'], m))

        return getattr(self, m)(self, REQUEST)

    def tabs_path_default(self, REQUEST,
                          # Static var
                          unquote=urllib.unquote,
                          ):
        steps = REQUEST._steps[:-1]
        script = REQUEST['BASEPATH1']
        linkpat = '
%s'
        out = []
        url = linkpat % (escape(script, 1), ' /')
        if not steps:
            return url
        last = steps.pop()
        for step in steps:
            script = '%s/%s' % (script, step)
            out.append(linkpat % (escape(script, 1), escape(unquote(step))))
        script = '%s/%s' % (script, last)
        out.append('%s'%
                   (escape(script, 1), escape(unquote(last))))
        return '%s%s' % (url, '/'.join(out))

    def tabs_path_info(self, script, path,
                       # Static vars
                       quote=urllib.quote,
                       ):
        out=[]
        while path[:1]=='/':
            path = path[1:]
        while path[-1:]=='/':
            path = path[:-1]
        while script[:1]=='/':
            script = script[1:]
        while script[-1:]=='/':
            script = script[:-1]
        path=path.split('/')[:-1]
        if script:
            path = [script] + path
        if not path:
            return ''
        script=''
        last=path[-1]
        del path[-1]
        for p in path:
            script="%s/%s" % (script, quote(p))
            out.append('%s' % (script, p))
        out.append(last)
        return '/'.join(out)

    class_manage_path__roles__=None
    def class_manage_path(self):
        if self.__class__.__module__[:1] != '*':
            return
        path = getattr(self.__class__, '_v_manage_path_roles', None)
        if path is None:
            meta_type = self.meta_type
            for zclass in self.getPhysicalRoot()._getProductRegistryData(
                'zclasses'):
                if zclass['meta_type'] == meta_type:
                    break
            else:
                self.__class__._v_manage_path_roles = ''
                return
            path = self.__class__._v_manage_path_roles = (
                '%(product)s/%(id)s' % zclass)
        if path:
            return '/Control_Panel/Products/%s/manage_workspace' % path

Globals.default__class_init__(Tabs)


class Navigation(ExtensionClass.Base):
    """Basic navigation UI support"""

    implements(INavigation)

    __ac_permissions__=(
        ('View management screens',
         ('manage', 'manage_menu', 'manage_top_frame',
          'manage_page_header',
          'manage_page_footer',
          )),
        )

    manage            =DTMLFile('dtml/manage', globals())
    manage_menu       =DTMLFile('dtml/menu', globals())

    manage_top_frame  =DTMLFile('dtml/manage_top_frame', globals())
    manage_page_header=DTMLFile('dtml/manage_page_header', globals())
    manage_page_footer=DTMLFile('dtml/manage_page_footer', globals())

    manage_form_title =DTMLFile('dtml/manage_form_title', globals(),
                                form_title='Add Form',
                                help_product=None,
                                help_topic=None)
    manage_form_title._setFuncSignature(
        varnames=('form_title', 'help_product', 'help_topic') )
    manage_form_title__roles__ = None

    zope_quick_start=DTMLFile('dtml/zope_quick_start', globals())
    zope_quick_start__roles__=None

    manage_copyright=DTMLFile('dtml/copyright', globals())
    manage_copyright__roles__ = None

    manage_zmi_logout__roles__ = None
    def manage_zmi_logout(self, REQUEST, RESPONSE):
        """Logout current user"""
        p = getattr(REQUEST, '_logout_path', None)
        if p is not None:
            return apply(self.restrictedTraverse(p))

        realm=RESPONSE.realm
        RESPONSE.setStatus(401)
        RESPONSE.setHeader('WWW-Authenticate', 'basic realm="%s"' % realm, 1)
        RESPONSE.setBody("""
Logout



You have been logged out.



""")
        return


    manage_zmi_prefs=DTMLFile('dtml/manage_zmi_prefs', globals())
    manage_zmi_prefs__roles__ = None

file = DTMLFile('dtml/manage_page_style.css', globals())
setattr(Navigation, 'manage_page_style.css', file)
setattr(Navigation, 'manage_page_style.css__roles__', None)

Globals.default__class_init__(Navigation)
Zope-2.9.4-retire_zpkg/lib/python/App/FindHomes.py0000644000175000017500000000610510337373524021740 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

"""Stick directory information in the built-in namespace."""

__version__='$Revision: 1.13 $'[11:-2]

import __builtin__
import os
import sys

import Products
from App.Common import package_home


try:
    home = os.environ['SOFTWARE_HOME']
except KeyError:
    home = os.path.abspath(package_home(Products.__dict__))

    home, e = os.path.split(home)
    d, e = os.path.split(home)
    if e == '.':
        home = d
    d, e = os.path.split(home)
    if e == '..':
        home = os.path.dirname(d)

home = os.path.realpath(home)
__builtin__.SOFTWARE_HOME = SOFTWARE_HOME = home

try:
    zhome = os.environ['ZOPE_HOME']
except KeyError:
    zhome = os.path.join(home, '..', '..')

__builtin__.ZOPE_HOME = ZOPE_HOME = os.path.realpath(zhome)

try:
    chome = os.environ['INSTANCE_HOME']
except KeyError:
    chome = home
    d, e = os.path.split(chome)
    if e == 'python':
        d, e = os.path.split(d)
        if e == 'lib':
            chome = d or os.getcwd()
else:
    chome = os.path.realpath(chome)
    inst_ppath = os.path.join(chome, 'lib', 'python')
    if os.path.isdir(inst_ppath):
        sys.path.insert(0, inst_ppath)

__builtin__.INSTANCE_HOME = INSTANCE_HOME = chome

# CLIENT_HOME allows ZEO clients to easily keep distinct pid and
# log files. This is currently an *experimental* feature, as I expect
# that increasing ZEO deployment will cause bigger changes to the
# way that z2.py works fairly soon.
try:
    CLIENT_HOME = os.environ['CLIENT_HOME']
except KeyError:
    CLIENT_HOME = os.path.join(INSTANCE_HOME, 'var')

__builtin__.CLIENT_HOME = CLIENT_HOME

# If there is a Products package in INSTANCE_HOME, add it to the
# Products package path
ip = os.path.join(INSTANCE_HOME, 'Products')
ippart = 0
ppath = Products.__path__
if os.path.isdir(ip) and ip not in ppath:
    disallow = os.environ.get('DISALLOW_LOCAL_PRODUCTS', '').lower()
    if disallow in ('no', 'off', '0', ''):
        ppath.insert(0, ip)
        ippart = 1

ppathpat = os.environ.get('PRODUCTS_PATH', None)
if ppathpat is not None:
    psep = os.pathsep
    if ppathpat.find('%(') >= 0:
        newppath = (ppathpat % {
            'PRODUCTS_PATH': psep.join(ppath ),
            'SOFTWARE_PRODUCTS': psep.join(ppath[ippart:] ),
            'INSTANCE_PRODUCTS': ip,
            }).split(psep)
    else:
        newppath = ppathpat.split(psep)
    del ppath[:]
    for p in filter(None, newppath):
        p = os.path.abspath(p)
        if os.path.isdir(p) and p not in ppath:
            ppath.append(p)
Zope-2.9.4-retire_zpkg/lib/python/App/DavLockManager.py0000644000175000017500000000762310337373524022710 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

__version__ = "$Revision: 1.8 $"[11:-2]

import OFS, Acquisition, Globals
from AccessControl import getSecurityManager, ClassSecurityInfo
from webdav.Lockable import wl_isLocked

class DavLockManager(OFS.SimpleItem.Item, Acquisition.Implicit):
    id           = 'DavLockManager'
    name = title = 'WebDAV Lock Manager'
    meta_type    = 'WebDAV Lock Manager'
    icon = 'p_/davlocked'

    security = ClassSecurityInfo()
    security.declareProtected('Manage WebDAV Locks',
                              'findLockedObjects', 'manage_davlocks',
                              'manage_unlockObjects')
    security.declarePrivate('unlockObjects')

    manage_davlocks=manage_main=manage=Globals.DTMLFile(
        'dtml/davLockManager', globals())
    manage_davlocks._setName('manage_davlocks')

    manage_options = (
        {'label': 'Write Locks', 'action': 'manage_main',
         'help': ('OFSP', 'DavLocks-ManageLocks.stx'), },
        )

    def locked_in_version(self): return 0

    def findLockedObjects(self, frompath=''):
        app = self.getPhysicalRoot()

        if frompath:
            if frompath[0] == '/': frompath = frompath[1:]
            # since the above will turn '/' into an empty string, check
            # for truth before chopping a final slash
            if frompath and frompath[-1] == '/': frompath= frompath[:-1]

        # Now we traverse to the node specified in the 'frompath' if
        # the user chose to filter the search, and run a ZopeFind with
        # the expression 'wl_isLocked()' to find locked objects.
        obj = app.unrestrictedTraverse(frompath)
        lockedobjs = self._findapply(obj, path=frompath)

        return lockedobjs

    def unlockObjects(self, paths=[]):
        app = self.getPhysicalRoot()

        for path in paths:
            ob = app.unrestrictedTraverse(path)
            ob.wl_clearLocks()

    def manage_unlockObjects(self, paths=[], REQUEST=None):
        " Management screen action to unlock objects. "
        if paths: self.unlockObjects(paths)
        if REQUEST is not None:
            m = '%s objects unlocked.' % len(paths)
            return self.manage_davlocks(self, REQUEST, manage_tabs_message=m)

    def _findapply(self, obj, result=None, path=''):
        # recursive function to actually dig through and find the locked
        # objects.

        if result is None:
            result = []
        base = Acquisition.aq_base(obj)
        if not hasattr(base, 'objectItems'):
            return result
        try: items = obj.objectItems()
        except: return result

        addresult = result.append
        for id, ob in items:
            if path: p = '%s/%s' % (path, id)
            else: p = id

            dflag = hasattr(ob, '_p_changed') and (ob._p_changed == None)
            bs = Acquisition.aq_base(ob)
            if wl_isLocked(ob):
                li = []
                addlockinfo = li.append
                for token, lock in ob.wl_lockItems():
                    addlockinfo({'owner':lock.getCreatorPath(),
                                 'token':token})
                addresult((p, li))
                dflag = 0
            if hasattr(bs, 'objectItems'):
                self._findapply(ob, result, p)
            if dflag: ob._p_deactivate()

        return result


Globals.default__class_init__(DavLockManager)
Zope-2.9.4-retire_zpkg/lib/python/App/Product.py0000644000175000017500000004606610337373524021516 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Product objects
"""
# The new Product model:
#
#   Products may be defined in the Products folder or by placing directories
#   in lib/python/Products.
#
#   Products in lib/python/Products may have up to three sources of information:
#
#       - Static information defined via Python.  This information is
#         described and made available via __init__.py.
#
#       - Dynamic object data that gets copied into the Bobobase.
#         This is contained in product.dat (which is obfuscated).
#
#       - Static extensions supporting the dynamic data.  These too
#         are obfuscated.
#
#   Products may be copied and pasted only within the products folder.
#
#   If a product is deleted (or cut), it is automatically recreated
#   on restart if there is still a product directory.


import os, re, zlib, marshal, cPickle
from cgi import escape
from urllib import quote

import transaction

import Globals, OFS.Folder, OFS.SimpleItem,  Acquisition, Products
import ZClasses, AccessControl.Owned
from OFS.Folder import Folder
from HelpSys.HelpSys import ProductHelp
from AccessControl import Unauthorized

from Factory import Factory
from Permission import PermissionManager
import RefreshFuncs
from App.config import getConfiguration


class ProductFolder(Folder):
    "Manage a collection of Products"

    id        ='Products'
    name=title='Product Management'
    meta_type ='Product Management'
    icon='p_/ProductFolder_icon'

    all_meta_types={'name': 'Product', 'action': 'manage_addProductForm'},
    meta_types=all_meta_types

    # This prevents subobjects from being owned!
    _owner=AccessControl.Owned.UnownableOwner

    def _product(self, name): return getattr(self, name)

    manage_addProductForm=Globals.DTMLFile('dtml/addProduct',globals())
    def manage_addProduct(self, id, title, REQUEST=None):
        ' '
        i=Product(id, title)
        self._setObject(id,i)
        if REQUEST is not None:
            return self.manage_main(self,REQUEST,update_menu=1)

    def _canCopy(self, op=0):
        return 0

Globals.InitializeClass(ProductFolder)


class Product(Folder, PermissionManager):
    """Model a product that can be created through the web.
    """
    meta_type='Product'
    icon='p_/Product_icon'
    version=''
    configurable_objects_=()
    redistributable=0
    import_error_=None
    _isBeingUsedAsAMethod_=1

    def new_version(self,
                    _intending=re.compile(r"[0-9]+").search, #TS
                    ):
        # Return a new version number based on the existing version.
        v=str(self.version)
        if not v: return '1.0'
        match = _intending(v)
        if match is None:
            return v
        while 1:
            # Find the last set of digits.
            m = _intending(v, match.end())
            if m is None:
                break
            else:
                match = m
        start = match.start()
        end = match.end()
        return v[:start] + str(1 + int(v[start:end])) + v[end:]


    meta_types=(
        ZClasses.meta_types+PermissionManager.meta_types+
        (
            {
                'name': Factory.meta_type,
                'action': 'manage_addPrincipiaFactoryForm'
                },
            )
        )

    manage_addZClassForm=ZClasses.methods['manage_addZClassForm']
    manage_addZClass    =ZClasses.methods['manage_addZClass']
    manage_subclassableClassNames=ZClasses.methods[
        'manage_subclassableClassNames']

    manage_options=(
        (Folder.manage_options[0],) +
        tuple(Folder.manage_options[2:]) +
        (
        {'label':'Distribution', 'action':'manage_distributionView',
         'help':('OFSP','Product_Distribution.stx')},
        )
        )

    manage_distributionView=Globals.DTMLFile(
        'dtml/distributionView',globals())

    _properties=Folder._properties+(
        {'id':'version', 'type': 'string'},
        )

    _reserved_names=('Help',)

    manage_addPrincipiaFactoryForm=Globals.DTMLFile(
        'dtml/addFactory',globals())
    def manage_addPrincipiaFactory(
        self, id, title, object_type, initial, permission=None, REQUEST=None):
        ' '
        i=Factory(id, title, object_type, initial, permission)
        self._setObject(id,i)
        factory = self._getOb(id)
        factory.initializePermission()
        if REQUEST is not None:
            return self.manage_main(self,REQUEST,update_menu=1)

    def __init__(self, id, title):
        self.id=id
        self.title=title

        # Workaround for unknown problem with help system and PluginIndexes product
        # NEEDS to be fixed for 2.4 ! (ajung)

        try:
            self._setObject('Help', ProductHelp('Help', id))
        except:
            pass

    def Destination(self):
        "Return the destination for factory output"
        return self
    Destination__roles__=None

    def DestinationURL(self):
        "Return the URL for the destination for factory output"
        return self.REQUEST['BASE4']
    DestinationURL__roles__=None

    def manage_distribute(self, version, RESPONSE, configurable_objects=[],
                          redistributable=0):
        "Set the product up to create a distribution and give a link"
        if self.__dict__.has_key('manage_options'):
            raise TypeError, 'This product is not redistributable.'
        self.version=version=version.strip()
        self.configurable_objects_=configurable_objects
        self.redistributable=redistributable
        RESPONSE.redirect('Distributions/%s-%s.tar.gz' %
                          (quote(self.id), quote(version)))

    def _distribution(self):
        # Return a distribution
        if self.__dict__.has_key('manage_options'):
            raise TypeError, 'This product is not redistributable.'

        id=self.id

        import rotor
        import tar
        rot=rotor.newrotor(id+' shshsh')
        ar=tar.tgzarchive("%s-%s" % (id, self.version))
        prefix="Products/%s/" % self.id

        # __init__.py
        ar.add(prefix+"__init__.py",
               '''"Product %s"
               ''' % id
               )

        # Extensions
        pp=id+'.'
        lpp=len(pp)
        ed=os.path.join(getConfiguration().instancehome,'Extensions')
        if os.path.exists(ed):
            for name in os.listdir(ed):
                suffix=''
                if name[:lpp]==pp:
                    path=os.path.join(ed, name)
                    try:
                        f=open(path)
                        data=f.read()
                        f.close()
                        if name[-3:]=='.py':
                            data=rot.encrypt(zlib.compress(data))
                            suffix='p'
                    except: data=None
                    if data:
                        ar.add("%sExtensions/%s%s" %
                               (prefix,name[lpp:],suffix),
                               data)

        # version.txt
        ar.add(prefix+'version.txt', self.version)

        # product.dat
        f=CompressedOutputFile(rot)
        if self.redistributable:
            # Since it's redistributable, make all objects configurable.
            objectList = self._objects
        else:
            objectList = tuple(filter(
                lambda o, obs=self.configurable_objects_:
                o['id'] in obs,
                self._objects))
        meta={
            '_objects': objectList,
            'redistributable': self.redistributable,
            }
        f.write(cPickle.dumps(meta,1))

        self._p_jar.exportFile(self._p_oid, f)
        ar.add(prefix+'product.dat', f.getdata())

        ar.finish()
        return str(ar)

    class Distributions(Acquisition.Explicit):
        "Product Distributions"

        def __bobo_traverse__(self, REQUEST, name):
            if name[-7:] != '.tar.gz':
                raise ValueError, 'Invalid Name: %s' % escape(name)
            l=name.find('-')
            id, version = name[:l], name[l+1:-7]
            product=self.aq_parent
            if product.id==id and product.version==version:
                return Distribution(product)

            raise ValueError, 'Invalid version or product id: %s' % escape(name)

    Distributions=Distributions()

    manage_traceback=Globals.DTMLFile('dtml/traceback',globals())
    manage_readme=Globals.DTMLFile('dtml/readme',globals())
    def manage_get_product_readme__(self):
        for name in ('README.txt', 'README.TXT', 'readme.txt'):
            path = os.path.join(self.home, name)
            if os.path.isfile(path):
                return open(path).read()
        return ''

    def permissionMappingPossibleValues(self):
        return self.possible_permissions()

    def zclass_product_name(self):
        return self.id

    def getProductHelp(self):
        """
        Returns the ProductHelp object associated
        with the Product.
        """
        if not hasattr(self, 'Help'):
            self._setObject('Help', ProductHelp('Help', self.id))
        return self.Help

    #
    # Product refresh
    #

    _refresh_dtml = Globals.DTMLFile('dtml/refresh', globals())

    def _readRefreshTxt(self, pid=None):
        refresh_txt = None
        if pid is None:
            pid = self.id
        for productDir in Products.__path__:
            found = 0
            for name in ('refresh.txt', 'REFRESH.txt', 'REFRESH.TXT'):
                p = os.path.join(productDir, pid, name)
                if os.path.exists(p):
                    found = 1
                    break
            if found:
                try:
                    file = open(p)
                    text = file.read()
                    file.close()
                    refresh_txt = text
                    break
                except:
                    # Not found here.
                    pass
        return refresh_txt

    def manage_refresh(self, REQUEST, manage_tabs_message=None):
        '''
        Displays the refresh management screen.
        '''
        error_type = error_value = error_tb = None
        exc = RefreshFuncs.getLastRefreshException(self.id)
        if exc is not None:
            error_type, error_value, error_tb = exc
            exc = None

        refresh_txt = self._readRefreshTxt()

        # Read the persistent refresh information.
        auto = RefreshFuncs.isAutoRefreshEnabled(self._p_jar, self.id)
        deps = RefreshFuncs.getDependentProducts(self._p_jar, self.id)

        # List all product modules.
        mods = RefreshFuncs.listRefreshableModules(self.id)
        loaded_modules = []
        prefix = 'Products.%s' % self.id
        prefixdot = prefix + '.'
        lpdot = len(prefixdot)
        for name, module in mods:
            if name == prefix or name[:lpdot] == prefixdot:
                name = name[lpdot:]
                if not name:
                    name = '__init__'
            loaded_modules.append(name)

        all_auto = RefreshFuncs.listAutoRefreshableProducts(self._p_jar)
        for pid in all_auto:
            # Ignore products that don't have a refresh.txt.
            if self._readRefreshTxt(pid) is None:
                all_auto.remove(pid)
        auto_other = filter(lambda productId, myId=self.id:
                            productId != myId, all_auto)

        # Return rendered DTML.
        return self._refresh_dtml(REQUEST,
                                  id=self.id,
                                  refresh_txt=refresh_txt,
                                  error_type=error_type,
                                  error_value=error_value,
                                  error_tb=error_tb,
                                  devel_mode=Globals.DevelopmentMode,
                                  auto_refresh_enabled=auto,
                                  auto_refresh_other=auto_other,
                                  dependent_products=deps,
                                  loaded_modules=loaded_modules,
                                  manage_tabs_message=manage_tabs_message,
                                  management_view='Refresh')

    def manage_performRefresh(self, REQUEST=None):
        '''
        Attempts to perform a refresh operation.
        '''
        if self._readRefreshTxt() is None:
            raise Unauthorized, 'refresh.txt not found'
        message = None
        if RefreshFuncs.performFullRefresh(self._p_jar, self.id):
            from ZODB import Connection
            Connection.resetCaches() # Clears cache in future connections.
            message = 'Product refreshed.'
        else:
            message = 'An exception occurred.'
        if REQUEST is not None:
            return self.manage_refresh(REQUEST, manage_tabs_message=message)

    def manage_enableAutoRefresh(self, enable=0, REQUEST=None):
        '''
        Changes the auto refresh flag for this product.
        '''
        if self._readRefreshTxt() is None:
            raise Unauthorized, 'refresh.txt not created'
        RefreshFuncs.enableAutoRefresh(self._p_jar, self.id, enable)
        if enable:
            message = 'Enabled auto refresh.'
        else:
            message = 'Disabled auto refresh.'
        if REQUEST is not None:
            return self.manage_refresh(REQUEST, manage_tabs_message=message)

    def manage_selectDependentProducts(self, selections=(), REQUEST=None):
        '''
        Selects which products to refresh simultaneously.
        '''
        if self._readRefreshTxt() is None:
            raise Unauthorized, 'refresh.txt not created'
        RefreshFuncs.setDependentProducts(self._p_jar, self.id, selections)
        if REQUEST is not None:
            return self.manage_refresh(REQUEST)

Globals.InitializeClass(Product)


class CompressedOutputFile:
    def __init__(self, rot):
        self._c=zlib.compressobj()
        self._r=[]
        self._rot=rot
        rot.encrypt('')

    def write(self, s):
        self._r.append(self._rot.encryptmore(self._c.compress(s)))

    def getdata(self):
        self._r.append(self._rot.encryptmore(self._c.flush()))
        return ''.join(self._r)

class CompressedInputFile:
    _done=0
    def __init__(self, f, rot):
        self._c=zlib.decompressobj()
        self._b=''
        if isinstance(rot, str):
            import rotor
            rot=rotor.newrotor(rot)
        self._rot=rot
        rot.decrypt('')
        self._f=f

    def _next(self):
        if self._done: return
        l=self._f.read(8196)
        if not l:
            l=self._c.flush()
            self._done=1
        else:
            l=self._c.decompress(self._rot.decryptmore(l))
        self._b=self._b+l

    def read(self, l=None):
        if l is None:
            while not self._done: self._next()
            l=len(self._b)
        else:
            while l > len(self._b) and not self._done: self._next()
        r=self._b[:l]
        self._b=self._b[l:]

        return r

    def readline(self):
        l=self._b.find('\n')
        while l < 0 and not self._done:
            self._next()
            l=self._b.find('\n')
        if l < 0: l=len(self._b)
        else: l=l+1
        r=self._b[:l]
        self._b=self._b[l:]
        return r

class Distribution:
    "A distribution builder"

    def __init__(self, product):
        self._product=product

    def index_html(self, RESPONSE):
        "Return distribution data"
        r=self._product._distribution()
        RESPONSE['content-type']='application/x-gzip'
        return r

def initializeProduct(productp, name, home, app):
    # Initialize a levered product
    products=app.Control_Panel.Products
    fver = ''

    if hasattr(productp, '__import_error__'): ie=productp.__import_error__
    else: ie=None

    # Retrieve version number from any suitable version.txt
    for fname in ('version.txt', 'VERSION.txt', 'VERSION.TXT'):
        try:
            fpath = os.path.join(home, fname)
            fhandle = open(fpath, 'r')
            fver = fhandle.read().strip()
            fhandle.close()
            break
        except IOError:
            continue

    old=None
    try:
        if ihasattr(products,name):
            old=getattr(products, name)
            if ihasattr(old,'version') and old.version==fver:
                if hasattr(old, 'import_error_') and \
                   old.import_error_==ie:
                    # Version hasn't changed. Don't reinitialize.
                    return old
    except: pass

    disable_distribution = 1
    try:
        f=CompressedInputFile(open(home+'/product.dat','rb'), name+' shshsh')
    except:
        f=fver and (" (%s)" % fver)
        product=Product(name, 'Installed product %s%s' % (name,f))
    else:
        meta=cPickle.Unpickler(f).load()
        product=app._p_jar.importFile(f)
        if meta.get('redistributable', 0):
            disable_distribution = 0
        product._objects=meta['_objects']

    if old is not None:
        app._manage_remove_product_meta_type(product)
        products._delObject(name)
        for id, v in old.objectItems():
            try: product._setObject(id, v)
            except: pass

    products._setObject(name, product)
    #product.__of__(products)._postCopy(products)
    product.icon='p_/InstalledProduct_icon'
    product.version=fver
    product.home=home
    if disable_distribution:
        product.manage_options=(Folder.manage_options[0],) + \
                                tuple(Folder.manage_options[2:])
        product._distribution=None
        product.manage_distribution=None
    product.thisIsAnInstalledProduct=1

    if ie:
        product.import_error_=ie
        product.title='Broken product %s' % name
        product.icon='p_/BrokenProduct_icon'
        product.manage_options=(
            {'label':'Traceback', 'action':'manage_traceback'},
            )

    for name in ('README.txt', 'README.TXT', 'readme.txt'):
        path = os.path.join(home, name)
        if os.path.isfile(path):
            product.manage_options=product.manage_options+(
                {'label':'README', 'action':'manage_readme'},
                )
            break

    # Ensure this product has a refresh tab.
    found = 0
    for option in product.manage_options:
        if option.get('label') == 'Refresh':
            found = 1
            break
    if not found:
        product.manage_options = product.manage_options + (
            {'label':'Refresh', 'action':'manage_refresh',
             'help': ('OFSP','Product_Refresh.stx')},)

    if not doInstall():
        transaction.abort()
        return product

    # Give the ZClass fixup code in Application
    Globals.__disk_product_installed__=1
    return product

def ihasattr(o, name):
    return hasattr(o, name) and o.__dict__.has_key(name)


def doInstall():
    return getConfiguration().enable_product_installation

Zope-2.9.4-retire_zpkg/lib/python/App/ImageFile.py0000755000175000017500000000735210362754567021726 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Image object that is stored in a file"""

__version__='$Revision: 1.20 $'[11:-2]

import os
import time

from App.config import getConfiguration
from zope.app.content_types import guess_content_type
from Globals import package_home
from Common import rfc1123_date
from DateTime import DateTime
import Acquisition
import Globals

class ImageFile(Acquisition.Explicit):
    """Image objects stored in external files."""

    def __init__(self,path,_prefix=None):
        if _prefix is None:
            _prefix=getConfiguration().softwarehome
        elif type(_prefix) is not type(''):
            _prefix=package_home(_prefix)
        path = os.path.join(_prefix, path)
        self.path=path
        if Globals.DevelopmentMode:
            # In development mode, a shorter time is handy
            max_age = 60 # One minute
        else:
            # A longer time reduces latency in production mode
            max_age = 3600 # One hour
        self.cch = 'public,max-age=%d' % max_age

        data = open(path, 'rb').read()
        content_type, enc=guess_content_type(path, data)
        if content_type:
            self.content_type=content_type
        else:
            self.content_type='image/%s' % path[path.rfind('.')+1:]
        self.__name__=path[path.rfind('/')+1:]
        self.lmt=float(os.stat(path)[8]) or time.time()
        self.lmh=rfc1123_date(self.lmt)


    def index_html(self, REQUEST, RESPONSE):
        """Default document"""
        # HTTP If-Modified-Since header handling. This is duplicated
        # from OFS.Image.Image - it really should be consolidated
        # somewhere...
        RESPONSE.setHeader('Content-Type', self.content_type)
        RESPONSE.setHeader('Last-Modified', self.lmh)
        RESPONSE.setHeader('Cache-Control', self.cch)
        header=REQUEST.get_header('If-Modified-Since', None)
        if header is not None:
            header=header.split(';')[0]
            # Some proxies seem to send invalid date strings for this
            # header. If the date string is not valid, we ignore it
            # rather than raise an error to be generally consistent
            # with common servers such as Apache (which can usually
            # understand the screwy date string as a lucky side effect
            # of the way they parse it).
            try:    mod_since=long(DateTime(header).timeTime())
            except: mod_since=None
            if mod_since is not None:
                if getattr(self, 'lmt', None):
                    last_mod = long(self.lmt)
                else:
                    last_mod = long(0)
                if last_mod > 0 and last_mod <= mod_since:
                    RESPONSE.setStatus(304)
                    return ''

        return open(self.path,'rb').read()

    HEAD__roles__=None
    def HEAD(self, REQUEST, RESPONSE):
        """ """
        RESPONSE.setHeader('Content-Type', self.content_type)
        RESPONSE.setHeader('Last-Modified', self.lmh)
        return ''

    def __len__(self):
        # This is bogus and needed because of the way Python tests truth.
        return 1

    def __str__(self):
        return '' % self.__name__
Zope-2.9.4-retire_zpkg/lib/python/App/Dialogs.py0000644000175000017500000000417610337373524021454 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

"""Common HTML dialog boxes

    MessageDialog(title, message, action, [target])

    A very simple dialog used to display an HTML page titled title,
    displaying message message and an OK button. Clicking the OK
    button will take the browser to the URL specified in action.
    The *optional* target argument can be used to force a (frames
    capable) browser to load the URL specified in action into a specific
    frame. (Specifying '_new' will cause the browser to load the
    specified URL into a new window, for example).

    example usage:
    
    return MessageDialog(title='Just thought you should know...',
                         message='You have wiped out your data.',
                         action='/paid_tech_support/prices.html',
                         target='_top')
    
"""

__version__='$Revision: 1.9 $'[11:-2]


from Globals import HTML

MessageDialog = HTML("""


&dtml-title;



TARGET="&dtml-target;">




  
  

  
!

  		
  
  


  

  
  

  		




  
  
  
  

  
  

  		






""", target='', action='manage_main', title='Changed')
Zope-2.9.4-retire_zpkg/lib/python/App/interfaces.py0000644000175000017500000000502610247566145022213 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2005 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""App z3 interfaces.

$Id: interfaces.py 30602 2005-06-02 11:24:21Z yuppie $
"""

from zope.interface import Attribute
from zope.interface import Interface


# XXX: might contain non-API methods and outdated comments;
#      not synced with ZopeBook API Reference;
#      based on App.Management.Navigation
class INavigation(Interface):

    """Basic navigation UI support"""

    manage = Attribute(""" """)
    manage_menu = Attribute(""" """)
    manage_top_frame = Attribute(""" """)
    manage_page_header = Attribute(""" """)
    manage_page_footer = Attribute(""" """)
    manage_form_title = Attribute("""Add Form""")
    zope_quick_start = Attribute(""" """)
    manage_copyright = Attribute(""" """)
    manage_zmi_prefs = Attribute(""" """)

    def manage_zmi_logout(REQUEST, RESPONSE):
        """Logout current user"""

INavigation.setTaggedValue('manage_page_style.css', Attribute(""" """))


# XXX: might contain non-API methods and outdated comments;
#      not synced with ZopeBook API Reference;
#      based on App.PersistentExtra.PersistentUtil
class IPersistentExtra(Interface):

    def bobobase_modification_time():
        """
        """

    def locked_in_version():
        """Was the object modified in any version?
        """

    def modified_in_version():
        """Was the object modified in this version?
        """


# XXX: might contain non-API methods and outdated comments;
#      not synced with ZopeBook API Reference;
#      based on App.Undo.UndoSupport
class IUndoSupport(Interface):

    manage_UndoForm = Attribute("""Manage Undo form""")

    def get_request_var_or_attr(name, default):
        """
        """

    def undoable_transactions(first_transaction=None,
                              last_transaction=None,
                              PrincipiaUndoBatchSize=None):
        """
        """

    def manage_undo_transactions(transaction_info=(), REQUEST=None):
        """
        """
Zope-2.9.4-retire_zpkg/lib/python/App/version_txt.py0000644000175000017500000000435410345323575022454 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Extract Zope 2 version information

$id$
"""
import os, sys, re
import Zope2

_version_string = None
_zope_version = None

def _test_reset():
    # Needed for testing.
    global _version_string, _zope_version
    _version_string = None
    _zope_version = None

def _prep_version_data():
    global _version_string, _zope_version
    if _version_string is None:
        v = sys.version_info
        pyver = "python %d.%d.%d, %s" % (v[0], v[1], v[2], sys.platform)
        fn = os.path.join(os.path.dirname(Zope2.__file__), 'version.txt')
        expr = re.compile(
            r'(?P[A-Za-z0-9]+) +(?P[0-9]+)'
            '\.(?P[0-9]+)\.(?P[0-9]+)'
            '(?P[A-Za-z]+)?(?P[0-9]+)?')
        try:
            s = open(fn).read().strip()
        except IOError:
            ss = 'unreleased version'
            _zope_version = (-1, -1, -1, '', -1)
        else:
            ss = re.sub("\(.*?\)\?","",s)
            dict = expr.match(s).groupdict()
            _zope_version = (
                int(dict.get('major') or -1),
                int(dict.get('minor') or -1),
                int(dict.get('micro') or -1),
                dict.get('status') or '',
                int(dict.get('release') or -1),
                )
        _version_string = "%s, %s" % (ss, pyver)


def version_txt():
    _prep_version_data()
    return '(%s)' % _version_string

def getZopeVersion():
    """
    Format of zope_version tuple:
    (major , minor , micro , status , release )
    If unreleased, integers may be -1.
    """
    _prep_version_data()
    return _zope_version
Zope-2.9.4-retire_zpkg/lib/python/App/ProductContext.py0000644000175000017500000003324610337373524023057 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Objects providing context for product initialization

$Id: ProductContext.py 40222 2005-11-18 15:46:28Z andreasjung $
"""

import os.path, re
import stat

from AccessControl.PermissionRole import PermissionRole
import Globals, os, OFS.ObjectManager, OFS.misc_, Products
import AccessControl.Permission
from App.Product import doInstall
from HelpSys import HelpTopic, APIHelpTopic
from HelpSys.HelpSys import ProductHelp
from FactoryDispatcher import FactoryDispatcher
from zLOG import LOG, WARNING
from DateTime import DateTime
from Interface.Implements import instancesOfObjectImplements
from zope.interface import implementedBy

import ZClasses # to enable 'PC.registerBaseClass()'

if not hasattr(Products, 'meta_types'):
    Products.meta_types=()
if not hasattr(Products, 'meta_classes'):
    Products.meta_classes={}
    Products.meta_class_info={}

_marker = []  # Create a new marker object


class ProductContext:

    def __init__(self, product, app, package):
        self.__prod=product
        self.__app=app
        self.__pack=package

    def registerClass(self, instance_class=None, meta_type='',
                      permission=None, constructors=(),
                      icon=None, permissions=None, legacy=(),
                      visibility="Global",interfaces=_marker,
                      container_filter=None
        ):
        """Register a constructor

        Keyword arguments are used to provide meta data:

        instance_class -- The class of the object that will be created.

          This is not currently used, but may be used in the future to
          increase object mobility.

        meta_type -- The kind of object being created
           This appears in add lists.  If not specified, then the class
           meta_type will be used.

        permission -- The permission name for the constructors.
           If not specified, then a permission name based on the
           meta type will be used.

        constructors -- A list of constructor methods
          A method can me a callable object with a __name__
          attribute giving the name the method should have in the
          product, or the method may be a tuple consisting of a
          name and a callable object.  The method must be picklable.

          The first method will be used as the initial method called
          when creating an object.

        icon -- The name of an image file in the package to
                be used for instances. Note that the class icon
                attribute will be set automagically if an icon is
                provided.

        permissions -- Additional permissions to be registered
           If not provided, then permissions defined in the
           class will be registered.

        legacy -- A list of legacy methods to be added to ObjectManager
                  for backward compatibility

        visibility -- "Global" if the object is globally visible, None else

        interfaces -- a list of the interfaces the object supports

        container_filter -- function that is called with an ObjectManager
           object as the only parameter, which should return a true object
           if the object is happy to be created in that container. The
           filter is called before showing ObjectManager's Add list,
           and before pasting (after object copy or cut), but not
           before calling an object's constructor.

        """
        pack=self.__pack
        initial=constructors[0]
        productObject=self.__prod
        pid=productObject.id

        if icon and instance_class is not None:
            setattr(instance_class, 'icon', 'misc_/%s/%s' %
                    (pid, os.path.split(icon)[1]))

        if permissions:
            if isinstance(permissions, basestring): # You goofed it!
                raise TypeError, ('Product context permissions should be a '
                    'list of permissions not a string', permissions)
            for p in permissions:
                if isinstance(p, tuple):
                    p, default= p
                    AccessControl.Permission.registerPermissions(
                        ((p, (), default),))
                else:
                    AccessControl.Permission.registerPermissions(
                        ((p, ()),))

        ############################################################
        # Constructor permission setup
        if permission is None:
            permission="Add %ss" % (meta_type or instance_class.meta_type)

        if isinstance(permission, tuple):
            permission, default = permission
        else:
            default = ('Manager',)

        pr=PermissionRole(permission,default)
        AccessControl.Permission.registerPermissions(
            ((permission, (), default),))
        ############################################################

        OM=OFS.ObjectManager.ObjectManager

        for method in legacy:
            if isinstance(method, tuple):
                name, method = method
                aliased = 1
            else:
                name=method.__name__
                aliased = 0
            if not OM.__dict__.has_key(name):
                setattr(OM, name, method)
                setattr(OM, name+'__roles__', pr)
                if aliased:
                    # Set the unaliased method name and its roles
                    # to avoid security holes.  XXX: All "legacy"
                    # methods need to be eliminated.
                    setattr(OM, method.__name__, method)
                    setattr(OM, method.__name__+'__roles__', pr)

        if isinstance(initial, tuple):
            name, initial = initial
        else:
            name = initial.__name__

        fd=getattr(pack, '__FactoryDispatcher__', None)
        if fd is None:
            class __FactoryDispatcher__(FactoryDispatcher):
                "Factory Dispatcher for a Specific Product"

            fd = pack.__FactoryDispatcher__ = __FactoryDispatcher__

        if not hasattr(pack, '_m'):
            pack._m = AttrDict(fd)

        m = pack._m

        if interfaces is _marker:
            if instance_class is None:
                interfaces = ()
            else:
                interfaces = tuple(implementedBy(instance_class))
                # BBB: Will be removed in Zope 2.11.
                interfaces += tuple(instancesOfObjectImplements(instance_class))

        Products.meta_types=Products.meta_types+(
            { 'name': meta_type or instance_class.meta_type,
              # 'action': The action in the add drop down in the ZMI. This is
              #           currently also required by the _verifyObjectPaste
              #           method of CopyContainers like Folders.
              'action': ('manage_addProduct/%s/%s' % (pid, name)),
              # 'product': Used by ProductRegistry for TTW products and by
              #            OFS.Application for refreshing products.
              #            This key might not be available.
              'product': pid,
              # 'permission': Guards the add action.
              'permission': permission,
              # 'visibility': A silly name. Doesn't have much to do with
              #               visibility. Allowed values: 'Global', None
              'visibility': visibility,
              # 'interfaces': A tuple of oldstyle and/or newstyle interfaces.
              'interfaces': interfaces,
              'instance': instance_class,
              'container_filter': container_filter
              },)

        m[name]=initial
        m[name+'__roles__']=pr

        for method in constructors[1:]:
            if isinstance(method, tuple):
                name, method = method
            else:
                name=os.path.split(method.__name__)[-1]
            if not productObject.__dict__.has_key(name):
                m[name]=method
                m[name+'__roles__']=pr

        if icon:
            name=os.path.split(icon)[1]
            icon=Globals.ImageFile(icon, self.__pack.__dict__)
            icon.__roles__=None
            if not hasattr(OFS.misc_.misc_, pid):
                setattr(OFS.misc_.misc_, pid, OFS.misc_.Misc_(pid, {}))
            getattr(OFS.misc_.misc_, pid)[name]=icon

    def registerZClass(self, Z, meta_type=None):
        #
        #   Convenience method, now deprecated -- clients should
        #   call 'ZClasses.createZClassForBase()' themselves at
        #   module import time, passing 'globals()', so that the
        #   ZClass will be available immediately.
        #
        base_class=Z._zclass_
        if meta_type is None:
            if hasattr(base_class, 'meta_type'): meta_type=base_class.meta_type
            else:                                meta_type=base_class.__name__

        module=base_class.__module__
        name=base_class.__name__

        key="%s/%s" % (module, name)

        if module[:9]=='Products.': module=module.split('.')[1]
        else: module=module.split('.')[0]

        info="%s: %s" % (module, name)

        Products.meta_class_info[key]=info # meta_type
        Products.meta_classes[key]=Z

    def registerBaseClass(self, base_class, meta_type=None):
        #
        #   Convenience method, now deprecated -- clients should
        #   call 'ZClasses.createZClassForBase()' themselves at
        #   module import time, passing 'globals()', so that the
        #   ZClass will be available immediately.
        #
        Z = ZClasses.createZClassForBase( base_class, self.__pack )
        return Z

    def getProductHelp(self):
        """
        Returns the ProductHelp associated with the current Product.
        """
        return self.__prod.__of__(self.__app.Control_Panel.Products).getProductHelp()

    def registerHelpTopic(self, id, topic):
        """
        Register a Help Topic for a product.
        """
        self.getProductHelp()._setObject(id, topic)

    def registerHelpTitle(self, title):
        """
        Sets the title of the Product's Product Help
        """
        h = self.getProductHelp()
        if getattr(h, 'title', None) != title:
            h.title = title

    def registerHelp(self, directory='help', clear=1,
            title_re=re.compile(r'(.+?)', re.I)):
        """
        Registers Help Topics for all objects in a directory.

        Nothing will be done if the files in the directory haven't
        changed since the last registerHelp call.

        'clear' indicates whether or not to delete all existing
        Topics from the Product.

        HelpTopics are created for these kind of files

        .dtml            -- DTMLHelpTopic
        .html .htm       -- TextHelpTopic
        .stx .txt        -- STXHelpTopic
        .jpg .png .gif   -- ImageHelpTopic
        .py              -- APIHelpTopic
        """

        if not doInstall():
            return

        help=self.getProductHelp()
        path=os.path.join(Globals.package_home(self.__pack.__dict__),
                          directory)

        # If help directory does not exist, log a warning and return.
        try:
            dir_mod_time=DateTime(os.stat(path)[stat.ST_MTIME])
        except OSError, (errno, text):
            LOG("Zope", WARNING, '%s: %s' % (text, path))
            return

        # test to see if nothing has changed since last registration
        if help.lastRegistered is not None and \
                help.lastRegistered >= dir_mod_time:
            return
        help.lastRegistered=DateTime()

        if clear:
            for id in help.objectIds(['Help Topic','Help Image']):
                help._delObject(id)

        for file in os.listdir(path):
            ext=os.path.splitext(file)[1]
            ext=ext.lower()
            if ext in ('.dtml',):
                contents = open(os.path.join(path,file),'rb').read()
                m = title_re.search(contents)
                if m:
                    title = m.group(1)
                else:
                    title = ''
                ht=HelpTopic.DTMLTopic(file, '', os.path.join(path,file))
                self.registerHelpTopic(file, ht)
            elif ext in ('.html', '.htm'):
                contents = open(os.path.join(path,file),'rb').read()
                m = title_re.search(contents)
                if m:
                    title = m.group(1)
                else:
                    title = ''
                ht=HelpTopic.TextTopic(file, title, os.path.join(path,file))
                self.registerHelpTopic(file, ht)
            elif ext in ('.stx', '.txt'):
                title=(open(os.path.join(path,file),'rb').readline()).split(':')[0]
                ht=HelpTopic.STXTopic(file, title, os.path.join(path, file))
                self.registerHelpTopic(file, ht)
            elif ext in ('.jpg', '.gif', '.png'):
                ht=HelpTopic.ImageTopic(file, '', os.path.join(path, file))
                self.registerHelpTopic(file, ht)
            elif ext in ('.py',):
                if file[0] == '_': # ignore __init__.py
                    continue
                ht=APIHelpTopic.APIHelpTopic(file, '', os.path.join(path, file))
                self.registerHelpTopic(file, ht)


class AttrDict:

    def __init__(self, ob):
        self.ob = ob

    def __setitem__(self, name, v):
        setattr(self.ob, name, v)
Zope-2.9.4-retire_zpkg/lib/python/App/tar.py0000644000175000017500000000754710337373524020665 0ustar  tseavertseaver##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
__doc__='''Simple module for writing tar files

$Id: tar.py 40222 2005-11-18 15:46:28Z andreasjung $'''
__version__='$Revision: 1.8 $'[11:-2]

import sys, time, zlib
try:
    from newstruct import pack
except:
    from struct import pack


def oct8(i):
    i=oct(i)
    return '0'*(6-len(i))+i+' \0'

def oct12(i):
    i=oct(i)
    v = '0'*(11-len(i))+i+' '
    if len(v) > 12:
        left = v[:-12]
        for c in left:
            if c != '0':
                raise ValueError, 'value too large for oct12'
        return v[-12:]
    return v

def pad(s,l):
    ls=len(s)
    if ls >= l: raise ValueError, 'value, %s, too wide for field (%d)' % (s,l)
    return s+'\0'*(l-ls)

class TarEntry:

    def __init__(self, path, data,
                 mode=0644, uid=0, gid=0, mtime=None, typeflag='0',
                 linkname='', uname='jim', gname='system', prefix=''):
        "Initialize a Tar archive entry"
        self.data=data
        if mtime is None: mtime=int(time.time())
        header=''.join([
            pad(path,      100),
            oct8(mode),
            oct8(uid),
            oct8(gid),
            oct12(len(data)),
            oct12(mtime),
            ' ' * 8,
            typeflag,
            pad(linkname,  100),
            'ustar\0',
            '00',
            pad(uname,      32),
            pad(gname,      32),
            '000000 \0',
            '000000 \0',
            pad(prefix,    155),
            '\0'*12,
            ])
        if len(header) != 512:
            raise ValueError, 'Bad Header Length: %d' % len(header)
        header=(header[:148]+
                oct8(reduce(lambda a,b: a+b, map(ord,header)))+
                header[156:])
        self.header=header

    def __str__(self):
        data=self.data
        l=len(data)
        if l%512: data=data+'\0'*(512-l%512)
        return self.header+data

def tar(entries):
    r=[]
    ra=r.append
    for name, data in entries:
        ra(str(TarEntry(name,data)))
    ra('\0'*1024)
    return ''.join(r)

def tgz(entries):
    c=zlib.compressobj()
    compress=c.compress
    r=[]
    ra=r.append
    for name, data in entries:
        ra(compress(str(TarEntry(name,data))))
    ra(compress('\0'*1024))
    ra(c.flush())
    return ''.join(r)

class tgzarchive:

    def __init__(self, name, time=None):
        self._f=gzFile('%s.tar' % name, time)

    def add(self, name, data):
        self._f.write(str(TarEntry(name,data)))

    def finish(self):
        self._f.write('\0'*1024)

    def __str__(self):
        return self._f.getdata()

class gzFile:
    _l=0
    _crc=zlib.crc32("")

    def __init__(self, name, t=None):
        self._c=zlib.compressobj(9, zlib.DEFLATED, -zlib.MAX_WBITS,
                                 zlib.DEF_MEM_LEVEL, 0)
        if t is None: t=time.time()
        self._r=['\037\213\010\010',
                 pack("... tags:

import pullparser, sys
f = file(sys.argv[1])
p = pullparser.PullParser(f)
for token in p.tags("a"):
    if token.type == "endtag": continue
    url = dict(token.attrs).get("href", "-")
    text = p.get_compressed_text(endat=("endtag", "a"))
    print "%s\t%s" % (url, text)

This program extracts the  from the document:

import pullparser, sys
f = file(sys.argv[1])
p = pullparser.PullParser(f)
if p.get_tag("title"):
    title = p.get_compressed_text()
    print "Title: %s" % title


Copyright 2003-2004 John J. Lee <jjl@pobox.com>
Copyright 1998-2001 Gisle Aas (original libwww-perl code)

This code is free software; you can redistribute it and/or modify it
under the terms of the BSD License.

"""

from __future__ import generators

import re, htmlentitydefs
import HTMLParser

__version__ = (0, 0, 6, None, None)  # 0.0.6b

class NoMoreTokensError(Exception): pass

class Token:
    """Represents an HTML tag, declaration, processing instruction etc.

    Behaves as both a tuple-like object (ie. iterable) and has attributes
    .type, .data and .attrs.

    >>> t = Token("starttag", "a", [("href", "http://www.python.org/")])
    >>> t == ("starttag", "a", [("href", "http://www.python.org/")])
    True
    >>> t.type, t.data == "starttag", "a"
    True
    >>> t.attrs == [("href", "http://www.python.org/")]
    True

    Public attributes

    type: one of "starttag", "endtag", "startendtag", "charref", "entityref",
     "data", "comment", "decl", "pi", after the corresponding methods of
     HTMLParser.HTMLParser
    data: For a tag, the tag name; otherwise, the relevant data carried by the
     tag, as a string
    attrs: list of (name, value) pairs representing HTML attributes
     (or None if token does not represent an opening tag)

    """
    def __init__(self, type, data, attrs=None):
        self.type = type
        self.data = data
        self.attrs = attrs
    def __iter__(self):
        return iter((self.type, self.data, self.attrs))
    def __eq__(self, other):
        type, data, attrs = other
        if (self.type == type and
            self.data == data and
            self.attrs == attrs):
            return True
        else:
            return False
    def __ne__(self, other): return not self.__eq__(other)
    def __repr__(self):
        args = ", ".join(map(repr, [self.type, self.data, self.attrs]))
        return self.__class__.__name__+"(%s)" % args

def iter_until_exception(fn, exception, *args, **kwds):
    while 1:
        try:
            yield fn(*args, **kwds)
        except exception:
            raise StopIteration

def caller():
    try:
        raise SyntaxError
    except:
        import sys
    return sys.exc_traceback.tb_frame.f_back.f_back.f_code.co_name

def unescape(data, entities):
    if data is None or '&' not in data:
        return data
    def replace_entities(match):
        ent = match.group()
        repl = entities.get(ent, ent)
        return repl
    return re.sub(r'&\S+?;', replace_entities, data)

def get_entitydefs():
    entitydefs = {}
    for name, char in htmlentitydefs.entitydefs.items():
        entitydefs["&%s;" % name] = char
    return entitydefs


class _AbstractParser:
    chunk = 1024
    compress_re = re.compile(r"\s+")
    entitydefs = htmlentitydefs.entitydefs
    def __init__(self, fh, textify={"img": "alt", "applet": "alt"},
                 encoding="ascii", entitydefs=None):
        """
        fh: file-like object (only a .read() method is required) from which to
         read HTML to be parsed
        textify: mapping used by .get_text() and .get_compressed_text() methods
         to represent opening tags as text
        encoding: encoding used to encode numeric character references by
         .get_text() and .get_compressed_text() ("ascii" by default)
        entitydefs: mapping like {'&': '&', ...} containing HTML entity
         definitions (a sensible default is used)

        If the element name of an opening tag matches a key in the textify
        mapping then that tag is converted to text.  The corresponding value is
        used to specify which tag attribute to obtain the text from.  textify
        maps from element names to either:

          - an HTML attribute name, in which case the HTML attribute value is
            used as its text value along with the element name in square
            brackets (eg."alt text goes here[IMG]", or, if the alt attribute
            were missing, just "[IMG]")
          - a callable object (eg. a function) which takes a Token and returns
            the string to be used as its text value

        If textify has no key for an element name, nothing is substituted for
        the opening tag.

        Public attributes:

        encoding and textify: see above

        """
        self._fh = fh
        self._tokenstack = []  # FIFO
        self.textify = textify
        self.encoding = encoding
        if entitydefs is None:
            entitydefs = get_entitydefs()
        self._entitydefs = entitydefs

    def __iter__(self): return self

    def tags(self, *names):
        return iter_until_exception(self.get_tag, NoMoreTokensError, *names)

    def tokens(self, *tokentypes):
        return iter_until_exception(self.get_token, NoMoreTokensError, *tokentypes)

    def next(self):
        try:
            return self.get_token()
        except NoMoreTokensError:
            raise StopIteration()

    def get_token(self, *tokentypes):
        """Pop the next Token object from the stack of parsed tokens.

        If arguments are given, they are taken to be token types in which the
        caller is interested: tokens representing other elements will be
        skipped.  Element names must be given in lower case.

        Raises NoMoreTokensError.

        """
        while 1:
            while self._tokenstack:
                token = self._tokenstack.pop(0)
                if tokentypes:
                    if token.type in tokentypes:
                        return token
                else:
                    return token
            data = self._fh.read(self.chunk)
            if not data:
                raise NoMoreTokensError()
            self.feed(data)

    def unget_token(self, token):
        """Push a Token back onto the stack."""
        self._tokenstack.insert(0, token)

    def get_tag(self, *names):
        """Return the next Token that represents an opening or closing tag.

        If arguments are given, they are taken to be element names in which the
        caller is interested: tags representing other elements will be skipped.
        Element names must be given in lower case.

        Raises NoMoreTokensError.

        """
        while 1:
            tok = self.get_token()
            if tok.type not in ["starttag", "endtag", "startendtag"]:
                continue
            if names:
                if tok.data in names:
                    return tok
            else:
                return tok

    def get_text(self, endat=None):
        """Get some text.

        endat: stop reading text at this tag (the tag is included in the
         returned text); endtag is a tuple (type, name) where type is
         "starttag", "endtag" or "startendtag", and name is the element name of
         the tag (element names must be given in lower case)

        If endat is not given, .get_text() will stop at the next opening or
        closing tag, or when there are no more tokens (no exception is raised).
        Note that .get_text() includes the text representation (if any) of the
        opening tag, but pushes the opening tag back onto the stack.  As a
        result, if you want to call .get_text() again, you need to call
        .get_tag() first (unless you want an empty string returned when you
        next call .get_text()).

        Entity references are translated using the entitydefs attribute (a
        mapping from names to characters like that provided by the standard
        module htmlentitydefs).  Named entity references that are not in this
        mapping are left unchanged.

        The textify attribute is used to translate opening tags into text: see
        the class docstring.

        """
        text = []
        tok = None
        while 1:
            try:
                tok = self.get_token()
            except NoMoreTokensError:
                # unget last token (not the one we just failed to get)
                if tok: self.unget_token(tok)
                break
            if tok.type == "data":
                text.append(tok.data)
            elif tok.type == "entityref":
                name = tok.data
                if name in self.entitydefs:
                    t = self.entitydefs[name]
                else:
                    t = "&%s;" % name
                text.append(t)
            elif tok.type == "charref":
                name, base = tok.data, 10
                if name.startswith('x'):
                    name, base= name[1:], 16
                t = unichr(int(name, base)).encode(self.encoding)
                text.append(t)
            elif tok.type in ["starttag", "endtag", "startendtag"]:
                tag_name = tok.data
                if tok.type in ["starttag", "startendtag"]:
                    alt = self.textify.get(tag_name)
                    if alt is not None:
                        if callable(alt):
                            text.append(alt(tok))
                        elif tok.attrs is not None:
                            for k, v in tok.attrs:
                                if k == alt:
                                    text.append(v)
                            text.append("[%s]" % tag_name.upper())
                if endat is None or endat == (tok.type, tag_name):
                    self.unget_token(tok)
                    break
        return "".join(text)

    def get_compressed_text(self, *args, **kwds):
        """
        As .get_text(), but collapses each group of contiguous whitespace to a
        single space character, and removes all initial and trailing
        whitespace.

        """
        text = self.get_text(*args, **kwds)
        text = text.strip()
        return self.compress_re.sub(" ", text)

    def handle_startendtag(self, tag, attrs):
        self._tokenstack.append(Token("startendtag", tag, attrs))
    def handle_starttag(self, tag, attrs):
        self._tokenstack.append(Token("starttag", tag, attrs))
    def handle_endtag(self, tag):
        self._tokenstack.append(Token("endtag", tag))
    def handle_charref(self, name):
        self._tokenstack.append(Token("charref", name))
    def handle_entityref(self, name):
        self._tokenstack.append(Token("entityref", name))
    def handle_data(self, data):
        self._tokenstack.append(Token("data", data))
    def handle_comment(self, data):
        self._tokenstack.append(Token("comment", data))
    def handle_decl(self, decl):
        self._tokenstack.append(Token("decl", decl))
    def unknown_decl(self, data):
        # XXX should this call self.error instead?
        #self.error("unknown declaration: " + `data`)
        self._tokenstack.append(Token("decl", data))
    def handle_pi(self, data):
        self._tokenstack.append(Token("pi", data))

    def unescape_attr(self, name):
        return unescape(name, self._entitydefs)
    def unescape_attrs(self, attrs):
        escaped_attrs = []
        for key, val in attrs:
            escaped_attrs.append((key, self.unescape_attr(val)))
        return escaped_attrs

class PullParser(_AbstractParser, HTMLParser.HTMLParser):
    def __init__(self, *args, **kwds):
        HTMLParser.HTMLParser.__init__(self)
        _AbstractParser.__init__(self, *args, **kwds)
    def unescape(self, name):
        # Use the entitydefs passed into constructor, not
        # HTMLParser.HTMLParser's entitydefs.
        return self.unescape_attr(name)

import sgmllib
class TolerantPullParser(_AbstractParser, sgmllib.SGMLParser):
    def __init__(self, *args, **kwds):
        sgmllib.SGMLParser.__init__(self)
        _AbstractParser.__init__(self, *args, **kwds)
    def unknown_starttag(self, tag, attrs):
        attrs = self.unescape_attrs(attrs)
        self._tokenstack.append(Token("starttag", tag, attrs))
    def unknown_endtag(self, tag):
        self._tokenstack.append(Token("endtag", tag))
���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/TreeDisplay/������������������������������������������������������0000755�0001750�0001750�00000000000�10447233610�021206� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/TreeDisplay/www/��������������������������������������������������0000755�0001750�0001750�00000000000�10447233610�022032� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/TreeDisplay/www/Plus_icon.gif�������������������������������������0000644�0001750�0001750�00000001550�10050234363�024451� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������GIF89a��������PPP���@���@�@�@��@������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������!����,������@E�H H`A�2tŋ.LH`D
19pɓ'~ �0aqJ(I|�;��������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/TreeDisplay/www/Blank_icon.gif������������������������������������0000644�0001750�0001750�00000001500�10050234363�024550� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������GIF89a��������PPP���@���@�@�@��@������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������!����,������@�H*\ȰÇ#JHŁ�;������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/TreeDisplay/www/Minus_icon.gif������������������������������������0000644�0001750�0001750�00000001544�10050234363�024624� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������GIF89a��������PPP���@���@�@�@��@������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������!����,������@A�H *|0 �6tHŃ%:qŏ IrƌOX2A=,Y2M�;������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/TreeDisplay/TreeTag.py��������������������������������������������0000644�0001750�0001750�00000054066�10337373524�023135� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################
"""Rendering object hierarchies as Trees
"""
__rcs_id__='$Id: TreeTag.py 40222 2005-11-18 15:46:28Z andreasjung $'
__version__='$Revision: 1.58 $'[11:-2]

from DocumentTemplate.DT_Util import *
from DocumentTemplate.DT_String import String

from cPickle import dumps
from string import translate
from urllib import quote, unquote
from zlib import compress, decompressobj
from binascii import b2a_base64, a2b_base64
import re

tbl=''.join(map(chr, range(256)))
tplus=tbl[:ord('+')]+'-'+tbl[ord('+')+1:]
tminus=tbl[:ord('-')]+'+'+tbl[ord('-')+1:]

class Tree:
    name='tree'
    blockContinuations=()
    expand=None

    def __init__(self, blocks):
        tname, args, section = blocks[0]
        args=parse_params(args, name=None, expr=None, nowrap=1,
                          expand=None, leaves=None,
                          header=None, footer=None,
                          branches=None, branches_expr=None,
                          sort=None, reverse=1, skip_unauthorized=1,
                          id=None, single=1, url=None,
                          # opened_decoration=None,
                          # closed_decoration=None,
                          # childless_decoration=None,
                          assume_children=1,
                          urlparam=None, prefix=None)
        has_key=args.has_key

        if has_key('') or has_key('name') or has_key('expr'):
            name,expr=name_param(args,'tree',1)

            if expr is not None: args['expr']=expr
            elif has_key(''): args['name']=name
        else: name='a tree tag'

        if has_key('branches_expr'):
            if has_key('branches'):
                raise ParseError, _tm(
                    'branches and  and branches_expr given', 'tree')
            args['branches_expr']=Eval(args['branches_expr']).eval
        elif not has_key('branches'): args['branches']='tpValues'

        if not has_key('id'): args['id']='tpId'
        if not has_key('url'): args['url']='tpURL'
        if not has_key('childless_decoration'):
            args['childless_decoration']=''

        prefix = args.get('prefix')
        if prefix and not simple_name(prefix):
            raise ParseError, _tm(
                'prefix is not a simple name', 'tree')

        self.__name__ = name
        self.section=section.blocks
        self.args=args


    def render(self,md):
        args=self.args
        have=args.has_key

        if have('name'): v=md[args['name']]
        elif have('expr'): v=args['expr'].eval(md)
        else: v=md.this
        return tpRender(v,md,self.section, self.args)

    __call__=render

String.commands['tree']=Tree

pyid=id # Copy builtin

simple_types = {str: 1, unicode: 1, int: 1, float: 1, long: 1,
                tuple: 1, list: 1, dict: 1}

def try_call_attr(ob, attrname, simple_types=simple_types):
    attr = getattr(ob, attrname)
    if type(attr) in simple_types:
        return attr
    try:
        return attr()
    except TypeError:
        return attr

def tpRender(self, md, section, args,
             try_call_attr=try_call_attr):
    """Render data organized as a tree.

    We keep track of open nodes using a cookie.  The cookie stored the
    tree state. State should be a tree represented like:

      []  # all closed
      ['eagle'], # eagle is open
      ['eagle'], ['jeep', [1983, 1985]]  # eagle, jeep, 1983 jeep and 1985 jeep

    where the items are object ids. The state will be pickled to a
    compressed and base64ed string that gets unencoded, uncompressed,
    and unpickled on the other side.

    Note that ids used in state need not be connected to urls, since
    state manipulation is internal to rendering logic.

    Note that to make unpickling safe, we use the MiniPickle module,
    that only creates safe objects
    """

    data=[]

    idattr=args['id']
    if hasattr(self, idattr):
        id = try_call_attr(self, idattr)
    elif hasattr(self, '_p_oid'): id=oid(self)
    else: id=pyid(self)

    try:
        # see if we are being run as a sub-document
        root=md['tree-root-url']
        url=md['tree-item-url']
        state=md['tree-state']
        diff=md['tree-diff']
        substate=md['-tree-substate-']
        colspan=md['tree-colspan']
        level=md['tree-level']

    except KeyError:
        # OK, we are a top-level invocation
        level=-1

        if md.has_key('collapse_all'):
            state=[id,[]],
        elif md.has_key('expand_all'):
            have_arg=args.has_key
            if have_arg('branches'):
                def get_items(node, branches=args['branches'], md=md):
                    get = md.guarded_getattr
                    if get is None:
                        get = getattr
                    items = get(node, branches)
                    return items()
            elif have_arg('branches_expr'):
                def get_items(node, branches_expr=args['branches_expr'], md=md):
                    md._push(InstanceDict(node, md))
                    items=branches_expr(md)
                    md._pop()
                    return items
            state=[id, tpValuesIds(self, get_items, args)],
        else:
            if md.has_key('tree-s'):
                state=md['tree-s']
                state=decode_seq(state)
                try:
                    if state[0][0] != id: state=[id,[]],
                except IndexError: state=[id,[]],
            else: state=[id,[]],

            if md.has_key('tree-e'):
                diff=decode_seq(md['tree-e'])
                apply_diff(state, diff, 1)

            if md.has_key('tree-c'):
                diff=decode_seq(md['tree-c'])
                apply_diff(state, diff, 0)

        colspan=tpStateLevel(state)
        substate=state
        diff=[]

        url=''
        root=md['URL']
        l=root.rfind('/')
        if l >= 0: root=root[l+1:]

    treeData={'tree-root-url': root,
              'tree-colspan': colspan,
              'tree-state': state }

    prefix = args.get('prefix')
    if prefix:
        for k, v in treeData.items():
            treeData[prefix + k[4:].replace('-', '_')] = v

    md._push(InstanceDict(self, md))
    md._push(treeData)

    try: tpRenderTABLE(self,id,root,url,state,substate,diff,data,colspan,
                       section,md,treeData, level, args)
    finally: md._pop(2)

    if state is substate and not (args.has_key('single') and args['single']):
        state=state or ([id],)
        state=encode_seq(state)
        md['RESPONSE'].setCookie('tree-s',state)

    return ''.join(data)

def tpRenderTABLE(self, id, root_url, url, state, substate, diff, data,
                  colspan, section, md, treeData, level=0, args=None,
                  try_call_attr=try_call_attr,
                  ):
    "Render a tree as a table"

    have_arg=args.has_key
    exp=0

    if level >= 0:
        urlattr=args['url']
        if urlattr and hasattr(self, urlattr):
            tpUrl = try_call_attr(self, urlattr)
            url = (url and ('%s/%s' % (url, tpUrl))) or tpUrl
            root_url = root_url or tpUrl

    ptreeData = add_with_prefix(treeData, 'tree', args.get('prefix'))
    ptreeData['tree-item-url']=url
    ptreeData['tree-level']=level
    ptreeData['tree-item-expanded']=0
    idattr=args['id']

    output=data.append

    items=None
    if (have_arg('assume_children') and args['assume_children']
        and substate is not state):
        # We should not compute children unless we have to.
        # See if we've been asked to expand our children.
        for i in range(len(substate)):
            sub=substate[i]
            if sub[0]==id:
                exp=i+1
                break
        if not exp: items=1

    get=md.guarded_getattr
    if get is None:
        get = getattr

    if items is None:
        if have_arg('branches') and hasattr(self, args['branches']):
            items = get(self, args['branches'])
            items = items()
        elif have_arg('branches_expr'):
            items=args['branches_expr'](md)

        if not items and have_arg('leaves'): items=1

    if items and items != 1:

        getitem = getattr(md, 'guarded_getitem', None)
        if getitem is not None:
            unauth=[]
            for index in range(len(items)):
                try:
                    getitem(items, index)
                except ValidationError:
                    unauth.append(index)
            if unauth:
                if have_arg('skip_unauthorized') and args['skip_unauthorized']:
                    items=list(items)
                    unauth.reverse()
                    for index in unauth: del items[index]
                else:
                    raise ValidationError, unauth

        if have_arg('sort'):
            # Faster/less mem in-place sort
            if type(items)==type(()):
                items=list(items)
            sort=args['sort']
            size=range(len(items))
            for i in size:
                v=items[i]
                k=getattr(v,sort)
                try:    k=k()
                except: pass
                items[i]=(k,v)
            items.sort()
            for i in size:
                items[i]=items[i][1]

        if have_arg('reverse'):
            items=list(items)           # Copy the list
            items.reverse()

    diff.append(id)


    _td_colspan='<td colspan="%s" style="white-space: nowrap"></td>'
    _td_single ='<td width="16" style="white-space: nowrap"></td>'

    sub=None
    if substate is state:
        output('<table cellspacing="0">\n')
        sub=substate[0]
        exp=items
    else:
        # Add prefix
        output('<tr>\n')

        # Add +/- icon
        if items:
            if level:
                if level > 3:   output(_td_colspan % (level-1))
                elif level > 1: output(_td_single * (level-1))
                output(_td_single)
                output('\n')
            output('<td width="16" valign="top" style="white-space: nowrap">')
            for i in range(len(substate)):
                sub=substate[i]
                if sub[0]==id:
                    exp=i+1
                    break

            ####################################
            # Mostly inline encode_seq for speed
            s=compress(dumps(diff,1))
            if len(s) > 57: s=encode_str(s)
            else:
                s=b2a_base64(s)[:-1]
                l=s.find('=')
                if l >= 0: s=s[:l]
            s=translate(s, tplus)
            ####################################

            script=md['BASEPATH1']

            # Propagate extra args through tree.
            if args.has_key( 'urlparam' ):
                param = args['urlparam']
                param = "%s&" % param
            else:
                param = ""

            if exp:
                ptreeData['tree-item-expanded']=1
                output('<a name="%s" href="%s?%stree-c=%s#%s">'
                       '<img src="%s/p_/mi" alt="-" border="0" /></a>' %
                       (id, root_url, param, s, id, script))
            else:
                output('<a name="%s" href="%s?%stree-e=%s#%s">'
                       '<img src="%s/p_/pl" alt="+" border="0" /></a>' %
                       (id, root_url, param, s, id, script))
            output('</td>\n')

        else:
            if level > 2:   output(_td_colspan % level)
            elif level > 0: output(_td_single  * level)
            output(_td_single)
            output('\n')


        # add item text
        dataspan=colspan-level
        output('<td%s%s valign="top" align="left">' %
               ((dataspan > 1 and (' colspan="%s"' % dataspan) or ''),
               (have_arg('nowrap') and args['nowrap'] and ' style="white-space: nowrap"' or ''))
               )
        output(render_blocks(section, md))
        output('</td>\n</tr>\n')


    if exp:

        level=level+1
        dataspan=colspan-level
        if level > 2:   h=_td_colspan % level
        elif level > 0: h=_td_single  * level
        else: h=''

        if have_arg('header'):
            doc=args['header']
            if md.has_key(doc): doc=md.getitem(doc,0)
            else: doc=None
            if doc is not None:
                output(doc(
                    None, md,
                    standard_html_header=(
                        '<tr>%s<td width="16" style="white-space: nowrap"></td>'
                        '<td%s valign="top">'
                        % (h,
                           (dataspan > 1 and (' colspan="%s"' % dataspan)
                            or ''))),
                    standard_html_footer='</td></tr>',
                    ))

        if items==1:
            # leaves
            if have_arg('leaves'):
                doc=args['leaves']
                if md.has_key(doc): doc=md.getitem(doc,0)
                else: doc=None
                if doc is not None:
                    treeData['-tree-substate-']=sub
                    ptreeData['tree-level']=level
                    md._push(treeData)
                    try: output(doc(
                        None,md,
                        standard_html_header=(
                            '<tr>%s<td width="16" style="white-space: nowrap"></td>'
                            '<td%s valign="top">'
                            % (h,
                               (dataspan > 1 and
                                (' colspan="%s"' % dataspan) or ''))),
                        standard_html_footer='</td></tr>',
                        ))
                    finally: md._pop(1)
        elif have_arg('expand'):
            doc=args['expand']
            if md.has_key(doc): doc=md.getitem(doc,0)
            else: doc=None
            if doc is not None:
                treeData['-tree-substate-']=sub
                ptreeData['tree-level']=level
                md._push(treeData)
                try: output(doc(
                    None,md,
                    standard_html_header=(
                        '<tr>%s<td width="16" style="white-space: nowrap"></td>'
                        '<td%s valign="top">'
                        % (h,
                           (dataspan > 1 and
                            (' colspan="%s"' % dataspan) or ''))),
                    standard_html_footer='</td></tr>',
                    ))
                finally: md._pop(1)
        else:
            __traceback_info__=sub, args, state, substate
            ids={}
            for item in items:
                if hasattr(item, idattr):
                    id = try_call_attr(item, idattr)
                elif hasattr(item, '_p_oid'): id=oid(item)
                else: id=pyid(item)
                if len(sub)==1: sub.append([])
                substate=sub[1]
                ids[id]=1
                md._push(InstanceDict(item,md))
                try: data=tpRenderTABLE(
                    item,id,root_url,url,state,substate,diff,data,
                    colspan, section, md, treeData, level, args)
                finally: md._pop()
                if not sub[1]: del sub[1]

            ids=ids.has_key
            for i in range(len(substate)-1,-1):
                if not ids(substate[i][0]): del substate[i]

        if have_arg('footer'):
            doc=args['footer']
            if md.has_key(doc): doc=md.getitem(doc,0)
            else: doc=None
            if doc is not None:
                output(doc(
                    None, md,
                    standard_html_header=(
                        '<tr>%s<td width="16" style="white-space: nowrap"></td>'
                        '<td%s valign="top">'
                        % (h,
                           (dataspan > 1 and (' colspan="%s"' % dataspan)
                            or ''))),
                    standard_html_footer='</td></tr>',
                    ))

    del diff[-1]
    if not diff: output('</table>\n')

    return data


def apply_diff(state, diff, expand):
    if not diff: return
    s=[None, state]
    diff.reverse()
    __traceback_info__=s, diff
    while diff:
        id=diff[-1]
        del diff[-1]
        if len(s)==1: s.append([])
        s=s[1]
        if type(s)==type(()):
            s=list(s)
        loc=-1
        for i in range(len(s)):
            if s[i][0]==id:
                loc=i
                break

        if loc >= 0:
            if not diff and not expand:
                del s[loc]
            else:
                s=s[loc]
        elif diff or expand:
            s.append([id,[]])
            s=s[-1][1]
            while diff:
                id=diff[-1]
                del diff[-1]
                if diff or expand:
                    s.append([id,[]])
                    s=s[-1][1]


def encode_seq(state):
    "Convert a sequence to an encoded string"
    state=compress(dumps(state))
    l=len(state)

    if l > 57:
        states=[]
        for i in range(0,l,57):
            states.append(b2a_base64(state[i:i+57])[:-1])
        state=''.join(states)
    else: state=b2a_base64(state)[:-1]

    l=state.find('=')
    if l >= 0: state=state[:l]

    state=translate(state, tplus)
    return state

def encode_str(state):
    "Convert a sequence to an encoded string"
    l=len(state)

    if l > 57:
        states=[]
        for i in range(0,l,57):
            states.append(b2a_base64(state[i:i+57])[:-1])
        state=''.join(states)
    else: state=b2a_base64(state)[:-1]

    l=state.find('=')
    if l >= 0: state=state[:l]

    state=translate(state, tplus)
    return state

def decode_seq(state):
    "Convert an encoded string to a sequence"
    state=translate(state, tminus)
    l=len(state)

    if l > 76:
        states=[]
        j=0
        for i in range(l/76):
            k=j+76
            states.append(a2b_base64(state[j:k]))
            j=k

        if j < l:
            state=state[j:]
            l=len(state)
            k=l%4
            if k: state=state+'='*(4-k)
            states.append(a2b_base64(state))
        state=''.join(states)
    else:
        l=len(state)
        k=l%4
        if k: state=state+'='*(4-k)
        state=a2b_base64(state)

    state=decompress(state)
    try: return list(MiniUnpickler(StringIO(state)).load())
    except: return []

def decompress(input,max_size=10240):
    # This sillyness can go away in python 2.2
    d = decompressobj()
    output = ''
    while input:
        fragment_size = max(1,(max_size-len(output))/1000)
        fragment,input = input[:fragment_size],input[fragment_size:]
        output += d.decompress(fragment)
        if len(output)>max_size:
            raise ValueError('Compressed input too large')
    return output+d.flush()

def tpStateLevel(state, level=0):
    for sub in state:
        if len(sub)==2: level = max(level, 1+tpStateLevel(sub[1]))
        else: level=max(level,1)
    return level

def tpValuesIds(self, get_items, args,
                try_call_attr=try_call_attr,
                ):
    # get_item(node) is a function that returns the subitems of node

    # This should build the ids of subitems which are
    # expandable (non-empty). Leaves should never be
    # in the state - it will screw the colspan counting.
    r=[]
    idattr=args['id']
    try:
        try: items=get_items(self)
        except AttributeError: items=()
        for item in items:
            try:
                if get_items(item):

                    if hasattr(item, idattr):
                        id = try_call_attr(item, idattr)
                    elif hasattr(item, '_p_oid'): id=oid(item)
                    else: id=pyid(item)

                    e=tpValuesIds(item, get_items, args)
                    if e: id=[id,e]
                    else: id=[id]
                    r.append(id)
            except: pass
    except: pass
    return r


def oid(self):
    return b2a_base64(str(self._p_oid))[:-1]


#icoSpace='<IMG SRC="Blank_icon" BORDER="0">'
#icoPlus ='<IMG SRC="Plus_icon" BORDER="0">'
#icoMinus='<IMG SRC="Minus_icon" BORDER="0">'





###############################################################################
## Everthing below here should go in a MiniPickle.py module, but keeping it
## internal makes an easier patch


import pickle
from cStringIO import StringIO


if pickle.format_version!="2.0":
    # Maybe the format changed, and opened a security hole
    raise 'Invalid pickle version'


class MiniUnpickler(pickle.Unpickler):
    """An unpickler that can only handle simple types.
    """
    def refuse_to_unpickle(self):
        raise pickle.UnpicklingError, 'Refused'

    dispatch = pickle.Unpickler.dispatch.copy()

    for k,v in dispatch.items():
        if k=='' or k in '().012FGIJKLMNTUVXS]adeghjlpqrstu}':
            # This key is necessary and safe, so leave it in the map
            pass
        else:
            dispatch[k] = refuse_to_unpickle
            # Anything unnecessary is banned, but here is some logic to explain why
            if k in [pickle.GLOBAL, pickle.OBJ, pickle.INST, pickle.REDUCE, pickle.BUILD]:
                # These are definite security holes
                pass
            elif k in [pickle.PERSID, pickle.BINPERSID]:
                # These are just unnecessary
                pass
    del k
    del v

def _should_succeed(x,binary=1):
    if x != MiniUnpickler(StringIO(pickle.dumps(x,binary))).load():
        raise ValueError(x)

def _should_fail(x,binary=1):
    try:
        MiniUnpickler(StringIO(pickle.dumps(x,binary))).load()
        raise ValueError(x)
    except pickle.UnpicklingError, e:
        if e[0]!='Refused': raise ValueError(x)

class _junk_class: pass

def _test():
    _should_succeed('hello')
    _should_succeed(1)
    _should_succeed(1L)
    _should_succeed(1.0)
    _should_succeed((1,2,3))
    _should_succeed([1,2,3])
    _should_succeed({1:2,3:4})
    _should_fail(open)
    _should_fail(_junk_class)
    _should_fail(_junk_class())

# Test MiniPickle on every import
_test()
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/TreeDisplay/__init__.py�������������������������������������������0000644�0001750�0001750�00000001212�10337373524�023322� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������##############################################################################
#
# Copyright (c) 2002 Zope Corporation and Contributors. All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE
#
##############################################################################

import TreeTag
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/���������������������������������������������������������0000755�0001750�0001750�00000000000�10447233610�020607� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/�������������������������������������������������0000755�0001750�0001750�00000000000�10447233610�022266� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/���������������������������������������������0000755�0001750�0001750�00000000000�10447233610�023076� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/����������������������������������0000755�0001750�0001750�00000000000�10447233610�025237� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/tables.py�������������������������0000644�0001750�0001750�00000045215�10322224711�027064� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Authors: David Goodger, David Priest
# Contact: goodger@python.org
# Revision: $Revision: 3165 $
# Date: $Date: 2005-04-05 04:55:06 +0200 (Tue, 05 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
Directives for table elements.
"""

__docformat__ = 'reStructuredText'


import sys
import os.path
from docutils import io, nodes, statemachine, utils
from docutils.utils import SystemMessagePropagation
from docutils.parsers.rst import directives

try:
    import csv                          # new in Python 2.3
except ImportError:
    csv = None

try:
    import urllib2
except ImportError:
    urllib2 = None

try:
    True
except NameError:                       # Python 2.2 & 2.1 compatibility
    True = not 0
    False = not 1


def table(name, arguments, options, content, lineno,
          content_offset, block_text, state, state_machine):
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text),
            line=lineno)
        return [warning]
    title, messages = make_title(arguments, state, lineno)
    node = nodes.Element()          # anonymous container for parsing
    state.nested_parse(content, content_offset, node)
    if len(node) != 1 or not isinstance(node[0], nodes.table):
        error = state_machine.reporter.error(
            'Error parsing content block for the "%s" directive: '
            'exactly one table expected.'
            % name, nodes.literal_block(block_text, block_text),
            line=lineno)
        return [error]
    table_node = node[0]
    table_node['classes'] += options.get('class', [])
    if title:
        table_node.insert(0, title)
    return [table_node] + messages

table.arguments = (0, 1, 1)
table.options = {'class': directives.class_option}
table.content = 1

def make_title(arguments, state, lineno):
    if arguments:
        title_text = arguments[0]
        text_nodes, messages = state.inline_text(title_text, lineno)
        title = nodes.title(title_text, '', *text_nodes)
    else:
        title = None
        messages = []
    return title, messages


if csv:
    class DocutilsDialect(csv.Dialect):

        """CSV dialect for `csv_table` directive function."""

        delimiter = ','
        quotechar = '"'
        doublequote = True
        skipinitialspace = True
        lineterminator = '\n'
        quoting = csv.QUOTE_MINIMAL

        def __init__(self, options):
            if options.has_key('delim'):
                self.delimiter = str(options['delim'])
            if options.has_key('keepspace'):
                self.skipinitialspace = False
            if options.has_key('quote'):
                self.quotechar = str(options['quote'])
            if options.has_key('escape'):
                self.doublequote = False
                self.escapechar = str(options['escape'])
            csv.Dialect.__init__(self)


    class HeaderDialect(csv.Dialect):

        """CSV dialect to use for the "header" option data."""

        delimiter = ','
        quotechar = '"'
        escapechar = '\\'
        doublequote = False
        skipinitialspace = True
        lineterminator = '\n'
        quoting = csv.QUOTE_MINIMAL


def csv_table(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    try:
        if ( not state.document.settings.file_insertion_enabled
             and (options.has_key('file') or options.has_key('url')) ):
            warning = state_machine.reporter.warning(
                '"%s" directive disabled.' % name,
                nodes.literal_block(block_text, block_text), line=lineno)
            return [warning]
        check_requirements(name, lineno, block_text, state_machine)
        title, messages = make_title(arguments, state, lineno)
        csv_data, source = get_csv_data(
            name, options, content, lineno, block_text, state, state_machine)
        table_head, max_header_cols = process_header_option(
            options, state_machine, lineno)
        rows, max_cols = parse_csv_data_into_rows(
            csv_data, DocutilsDialect(options), source, options)
        max_cols = max(max_cols, max_header_cols)
        header_rows = options.get('header-rows', 0) # default 0
        stub_columns = options.get('stub-columns', 0) # default 0
        check_table_dimensions(
            rows, header_rows, stub_columns, name, lineno,
            block_text, state_machine)
        table_head.extend(rows[:header_rows])
        table_body = rows[header_rows:]
        col_widths = get_column_widths(
            max_cols, name, options, lineno, block_text, state_machine)
        extend_short_rows_with_empty_cells(max_cols, (table_head, table_body))
    except SystemMessagePropagation, detail:
        return [detail.args[0]]
    except csv.Error, detail:
        error = state_machine.reporter.error(
            'Error with CSV data in "%s" directive:\n%s' % (name, detail),
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    table = (col_widths, table_head, table_body)
    table_node = state.build_table(table, content_offset, stub_columns)
    table_node['classes'] += options.get('class', [])
    if title:
        table_node.insert(0, title)
    return [table_node] + messages

csv_table.arguments = (0, 1, 1)
csv_table.options = {'header-rows': directives.nonnegative_int,
                     'stub-columns': directives.nonnegative_int,
                     'header': directives.unchanged,
                     'widths': directives.positive_int_list,
                     'file': directives.path,
                     'url': directives.uri,
                     'encoding': directives.encoding,
                     'class': directives.class_option,
                     # field delimiter char
                     'delim': directives.single_char_or_whitespace_or_unicode,
                     # treat whitespace after delimiter as significant
                     'keepspace': directives.flag,
                     # text field quote/unquote char:
                     'quote': directives.single_char_or_unicode,
                     # char used to escape delim & quote as-needed:
                     'escape': directives.single_char_or_unicode,}
csv_table.content = 1

def check_requirements(name, lineno, block_text, state_machine):
    if not csv:
        error = state_machine.reporter.error(
            'The "%s" directive is not compatible with this version of '
            'Python (%s).  Requires the "csv" module, new in Python 2.3.'
            % (name, sys.version.split()[0]),
            nodes.literal_block(block_text, block_text), line=lineno)
        raise SystemMessagePropagation(error)

def get_csv_data(name, options, content, lineno, block_text,
                 state, state_machine):
    """
    CSV data can come from the directive content, from an external file, or
    from a URL reference.
    """
    encoding = options.get('encoding', state.document.settings.input_encoding)
    if content:                         # CSV data is from directive content
        if options.has_key('file') or options.has_key('url'):
            error = state_machine.reporter.error(
                  '"%s" directive may not both specify an external file and '
                  'have content.' % name,
                  nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(error)
        source = content.source(0)
        csv_data = content
    elif options.has_key('file'):       # CSV data is from an external file
        if options.has_key('url'):
            error = state_machine.reporter.error(
                  'The "file" and "url" options may not be simultaneously '
                  'specified for the "%s" directive.' % name,
                  nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(error)
        source_dir = os.path.dirname(
            os.path.abspath(state.document.current_source))
        source = os.path.normpath(os.path.join(source_dir, options['file']))
        source = utils.relative_path(None, source)
        try:
            state.document.settings.record_dependencies.add(source)
            csv_file = io.FileInput(
                source_path=source, encoding=encoding,
                error_handler
                    =state.document.settings.input_encoding_error_handler,
                handle_io_errors=None)
            csv_data = csv_file.read().splitlines()
        except IOError, error:
            severe = state_machine.reporter.severe(
                  'Problems with "%s" directive path:\n%s.' % (name, error),
                  nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(severe)
    elif options.has_key('url'):        # CSV data is from a URL
        if not urllib2:
            severe = state_machine.reporter.severe(
                  'Problems with the "%s" directive and its "url" option: '
                  'unable to access the required functionality (from the '
                  '"urllib2" module).' % name,
                  nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(severe)
        source = options['url']
        try:
            csv_text = urllib2.urlopen(source).read()
        except (urllib2.URLError, IOError, OSError, ValueError), error:
            severe = state_machine.reporter.severe(
                  'Problems with "%s" directive URL "%s":\n%s.'
                  % (name, options['url'], error),
                  nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(severe)
        csv_file = io.StringInput(
            source=csv_text, source_path=source, encoding=encoding,
            error_handler=state.document.settings.input_encoding_error_handler)
        csv_data = csv_file.read().splitlines()
    else:
        error = state_machine.reporter.warning(
            'The "%s" directive requires content; none supplied.' % (name),
            nodes.literal_block(block_text, block_text), line=lineno)
        raise SystemMessagePropagation(error)
    return csv_data, source

def process_header_option(options, state_machine, lineno):
    source = state_machine.get_source(lineno - 1)
    table_head = []
    max_header_cols = 0
    if options.has_key('header'):       # separate table header in option
        rows, max_header_cols = parse_csv_data_into_rows(
            options['header'].split('\n'), HeaderDialect(), source, options)
        table_head.extend(rows)
    return table_head, max_header_cols

def parse_csv_data_into_rows(csv_data, dialect, source, options):
    # csv.py doesn't do Unicode; encode temporarily as UTF-8
    csv_reader = csv.reader([line.encode('utf-8') for line in csv_data],
                            dialect=dialect)
    rows = []
    max_cols = 0
    for row in csv_reader:
        row_data = []
        for cell in row:
            # decode UTF-8 back to Unicode
            cell_text = unicode(cell, 'utf-8')
            cell_data = (0, 0, 0, statemachine.StringList(
                cell_text.splitlines(), source=source))
            row_data.append(cell_data)
        rows.append(row_data)
        max_cols = max(max_cols, len(row))
    return rows, max_cols

def check_table_dimensions(rows, header_rows, stub_columns, name, lineno,
                           block_text, state_machine):
    if len(rows) < header_rows:
        error = state_machine.reporter.error(
            '%s header row(s) specified but only %s row(s) of data supplied '
            '("%s" directive).' % (header_rows, len(rows), name),
            nodes.literal_block(block_text, block_text), line=lineno)
        raise SystemMessagePropagation(error)
    if len(rows) == header_rows > 0:
        error = state_machine.reporter.error(
            'Insufficient data supplied (%s row(s)); no data remaining for '
            'table body, required by "%s" directive.' % (len(rows), name),
            nodes.literal_block(block_text, block_text), line=lineno)
        raise SystemMessagePropagation(error)
    for row in rows:
        if len(row) < stub_columns:
            error = state_machine.reporter.error(
                '%s stub column(s) specified but only %s columns(s) of data '
                'supplied ("%s" directive).' % (stub_columns, len(row), name),
                nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(error)
        if len(row) == stub_columns > 0:
            error = state_machine.reporter.error(
                'Insufficient data supplied (%s columns(s)); no data remaining '
                'for table body, required by "%s" directive.'
                % (len(row), name),
                nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(error)

def get_column_widths(max_cols, name, options, lineno, block_text,
                      state_machine):
    if options.has_key('widths'):
        col_widths = options['widths']
        if len(col_widths) != max_cols:
            error = state_machine.reporter.error(
              '"%s" widths do not match the number of columns in table (%s).'
              % (name, max_cols),
              nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(error)
    elif max_cols:
        col_widths = [100 / max_cols] * max_cols
    else:
        error = state_machine.reporter.error(
            'No table data detected in CSV file.',
            nodes.literal_block(block_text, block_text), line=lineno)
        raise SystemMessagePropagation(error)
    return col_widths

def extend_short_rows_with_empty_cells(columns, parts):
    for part in parts:
        for row in part:
            if len(row) < columns:
                row.extend([(0, 0, 0, [])] * (columns - len(row)))

def list_table(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
    """
    Implement tables whose data is encoded as a uniform two-level bullet list.
    For further ideas, see
    http://docutils.sf.net/docs/dev/rst/alternatives.html#list-driven-tables
    """ 
    if not content:
        error = state_machine.reporter.error(
            'The "%s" directive is empty; content required.' % name,
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    title, messages = make_title(arguments, state, lineno)
    node = nodes.Element()          # anonymous container for parsing
    state.nested_parse(content, content_offset, node)
    try:
        num_cols, col_widths = check_list_content(
            node, name, options, content, lineno, block_text, state_machine)
        table_data = [[item.children for item in row_list[0]]
                      for row_list in node[0]]
        header_rows = options.get('header-rows', 0) # default 0
        stub_columns = options.get('stub-columns', 0) # default 0
        check_table_dimensions(
            table_data, header_rows, stub_columns, name, lineno,
            block_text, state_machine)
    except SystemMessagePropagation, detail:
        return [detail.args[0]]
    table_node = build_table_from_list(table_data, col_widths,
                                       header_rows, stub_columns)
    table_node['classes'] += options.get('class', [])
    if title:
        table_node.insert(0, title)
    return [table_node] + messages

list_table.arguments = (0, 1, 1)
list_table.options = {'header-rows': directives.nonnegative_int,
                      'stub-columns': directives.nonnegative_int,
                      'widths': directives.positive_int_list,
                      'class': directives.class_option}
list_table.content = 1

def check_list_content(node, name, options, content, lineno, block_text,
                       state_machine):
    if len(node) != 1 or not isinstance(node[0], nodes.bullet_list):
        error = state_machine.reporter.error(
            'Error parsing content block for the "%s" directive: '
            'exactly one bullet list expected.' % name,
            nodes.literal_block(block_text, block_text), line=lineno)
        raise SystemMessagePropagation(error)
    list_node = node[0]
    # Check for a uniform two-level bullet list:
    for item_index in range(len(list_node)):
        item = list_node[item_index]
        if len(item) != 1 or not isinstance(item[0], nodes.bullet_list):
            error = state_machine.reporter.error(
                'Error parsing content block for the "%s" directive: '
                'two-level bullet list expected, but row %s does not contain '
                'a second-level bullet list.' % (name, item_index + 1),
                nodes.literal_block(block_text, block_text), line=lineno)
            raise SystemMessagePropagation(error)
        elif item_index:
            if len(item[0]) != num_cols:
                error = state_machine.reporter.error(
                    'Error parsing content block for the "%s" directive: '
                    'uniform two-level bullet list expected, but row %s does '
                    'not contain the same number of items as row 1 (%s vs %s).'
                    % (name, item_index + 1, len(item[0]), num_cols),
                    nodes.literal_block(block_text, block_text), line=lineno)
                raise SystemMessagePropagation(error)
        else:
            num_cols = len(item[0])
    col_widths = get_column_widths(
        num_cols, name, options, lineno, block_text, state_machine)
    if len(col_widths) != num_cols:
        error = state_machine.reporter.error(
            'Error parsing "widths" option of the "%s" directive: '
            'number of columns does not match the table data (%s vs %s).'
            % (name, len(col_widths), num_cols),
            nodes.literal_block(block_text, block_text), line=lineno)
        raise SystemMessagePropagation(error)
    return num_cols, col_widths

def build_table_from_list(table_data, col_widths, header_rows, stub_columns):
    table = nodes.table()
    tgroup = nodes.tgroup(cols=len(col_widths))
    table += tgroup
    for col_width in col_widths:
        colspec = nodes.colspec(colwidth=col_width)
        if stub_columns:
            colspec.attributes['stub'] = 1
            stub_columns -= 1
        tgroup += colspec
    rows = []
    for row in table_data:
        row_node = nodes.row()
        for cell in row:
            entry = nodes.entry()
            entry += cell
            row_node += entry
        rows.append(row_node)
    if header_rows:
        thead = nodes.thead()
        thead.extend(rows[:header_rows])
        tgroup += thead
    tbody = nodes.tbody()
    tbody.extend(rows[header_rows:])
    tgroup += tbody
    return table
�����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/parts.py��������������������������0000644�0001750�0001750�00000011104�10322224711�026731� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger, Dmitry Jemerov
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3199 $
# Date: $Date: 2005-04-09 03:32:29 +0200 (Sat, 09 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
Directives for document parts.
"""

__docformat__ = 'reStructuredText'

from docutils import nodes, languages
from docutils.transforms import parts
from docutils.parsers.rst import directives


backlinks_values = ('top', 'entry', 'none')

def backlinks(arg):
    value = directives.choice(arg, backlinks_values)
    if value == 'none':
        return None
    else:
        return value

def contents(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    """
    Table of contents.

    The table of contents is generated in two passes: initial parse and
    transform.  During the initial parse, a 'pending' element is generated
    which acts as a placeholder, storing the TOC title and any options
    internally.  At a later stage in the processing, the 'pending' element is
    replaced by a 'topic' element, a title and the table of contents proper.
    """
    if not (state_machine.match_titles
            or isinstance(state_machine.node, nodes.sidebar)):
        error = state_machine.reporter.error(
              'The "%s" directive may not be used within topics '
              'or body elements.' % name,
              nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    document = state_machine.document
    language = languages.get_language(document.settings.language_code)
    if arguments:
        title_text = arguments[0]
        text_nodes, messages = state.inline_text(title_text, lineno)
        title = nodes.title(title_text, '', *text_nodes)
    else:
        messages = []
        if options.has_key('local'):
            title = None
        else:
            title = nodes.title('', language.labels['contents'])
    topic = nodes.topic(classes=['contents'])
    topic['classes'] += options.get('class', [])
    if title:
        name = title.astext()
        topic += title
    else:
        name = language.labels['contents']
    name = nodes.fully_normalize_name(name)
    if not document.has_name(name):
        topic['names'].append(name)
    document.note_implicit_target(topic)
    pending = nodes.pending(parts.Contents, rawsource=block_text)
    pending.details.update(options)
    document.note_pending(pending)
    topic += pending
    return [topic] + messages

contents.arguments = (0, 1, 1)
contents.options = {'depth': directives.nonnegative_int,
                    'local': directives.flag,
                    'backlinks': backlinks,
                    'class': directives.class_option}

def sectnum(name, arguments, options, content, lineno,
            content_offset, block_text, state, state_machine):
    """Automatic section numbering."""
    pending = nodes.pending(parts.SectNum)
    pending.details.update(options)
    state_machine.document.note_pending(pending)
    return [pending]

sectnum.options = {'depth': int,
                   'start': int,
                   'prefix': directives.unchanged_required,
                   'suffix': directives.unchanged_required}

def header_footer(node, name, arguments, options, content, lineno,
                  content_offset, block_text, state, state_machine):
    """Contents of document header or footer."""
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text),
            line=lineno)
        node.append(nodes.paragraph(
            '', 'Problem with the "%s" directive: no content supplied.' % name))
        return [warning]
    text = '\n'.join(content)
    state.nested_parse(content, content_offset, node)
    return []

def header(name, arguments, options, content, lineno,
           content_offset, block_text, state, state_machine):
    decoration = state_machine.document.get_decoration()
    node = decoration.get_header()
    return header_footer(node, name, arguments, options, content, lineno,
                         content_offset, block_text, state, state_machine)

header.content = 1

def footer(name, arguments, options, content, lineno,
           content_offset, block_text, state, state_machine):
    decoration = state_machine.document.get_decoration()
    node = decoration.get_footer()
    return header_footer(node, name, arguments, options, content, lineno,
                         content_offset, block_text, state, state_machine)

footer.content = 1
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/__init__.py�����������������������0000644�0001750�0001750�00000035103�10322224711�027344� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@python.org
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
This package contains directive implementation modules.

The interface for directive functions is as follows::

    def directive_fn(name, arguments, options, content, lineno,
                     content_offset, block_text, state, state_machine):
        code...

    # Set function attributes:
    directive_fn.arguments = ...
    directive_fn.options = ...
    direcitve_fn.content = ...

Parameters:

- ``name`` is the directive type or name (string).

- ``arguments`` is a list of positional arguments (strings).

- ``options`` is a dictionary mapping option names (strings) to values (type
  depends on option conversion functions; see below).

- ``content`` is a list of strings, the directive content.

- ``lineno`` is the line number of the first line of the directive.

- ``content_offset`` is the line offset of the first line of the content from
  the beginning of the current input.  Used when initiating a nested parse.

- ``block_text`` is a string containing the entire directive.  Include it as
  the content of a literal block in a system message if there is a problem.

- ``state`` is the state which called the directive function.

- ``state_machine`` is the state machine which controls the state which called
  the directive function.

Function attributes, interpreted by the directive parser (which calls the
directive function):

- ``arguments``: A 3-tuple specifying the expected positional arguments, or
  ``None`` if the directive has no arguments.  The 3 items in the tuple are
  ``(required, optional, whitespace OK in last argument)``:

  1. The number of required arguments.
  2. The number of optional arguments.
  3. A boolean, indicating if the final argument may contain whitespace.

  Arguments are normally single whitespace-separated words.  The final
  argument may contain whitespace if the third item in the argument spec tuple
  is 1/True.  If the form of the arguments is more complex, specify only one
  argument (either required or optional) and indicate that final whitespace is
  OK; the client code must do any context-sensitive parsing.

- ``options``: A dictionary, mapping known option names to conversion
  functions such as `int` or `float`.  ``None`` or an empty dict implies no
  options to parse.  Several directive option conversion functions are defined
  in this module.

  Option conversion functions take a single parameter, the option argument (a
  string or ``None``), validate it and/or convert it to the appropriate form.
  Conversion functions may raise ``ValueError`` and ``TypeError`` exceptions.

- ``content``: A boolean; true if content is allowed.  Client code must handle
  the case where content is required but not supplied (an empty content list
  will be supplied).

Directive functions return a list of nodes which will be inserted into the
document tree at the point where the directive was encountered (can be an
empty list).

See `Creating reStructuredText Directives`_ for more information.

.. _Creating reStructuredText Directives:
   http://docutils.sourceforge.net/docs/howto/rst-directives.html
"""

__docformat__ = 'reStructuredText'

import re
import codecs
from docutils import nodes
from docutils.parsers.rst.languages import en as _fallback_language_module


_directive_registry = {
      'attention': ('admonitions', 'attention'),
      'caution': ('admonitions', 'caution'),
      'danger': ('admonitions', 'danger'),
      'error': ('admonitions', 'error'),
      'important': ('admonitions', 'important'),
      'note': ('admonitions', 'note'),
      'tip': ('admonitions', 'tip'),
      'hint': ('admonitions', 'hint'),
      'warning': ('admonitions', 'warning'),
      'admonition': ('admonitions', 'admonition'),
      'sidebar': ('body', 'sidebar'),
      'topic': ('body', 'topic'),
      'line-block': ('body', 'line_block'),
      'parsed-literal': ('body', 'parsed_literal'),
      'rubric': ('body', 'rubric'),
      'epigraph': ('body', 'epigraph'),
      'highlights': ('body', 'highlights'),
      'pull-quote': ('body', 'pull_quote'),
      'compound': ('body', 'compound'),
      #'questions': ('body', 'question_list'),
      'table': ('tables', 'table'),
      'csv-table': ('tables', 'csv_table'),
      'list-table': ('tables', 'list_table'),
      'image': ('images', 'image'),
      'figure': ('images', 'figure'),
      'contents': ('parts', 'contents'),
      'sectnum': ('parts', 'sectnum'),
      'header': ('parts', 'header'),
      'footer': ('parts', 'footer'),
      #'footnotes': ('parts', 'footnotes'),
      #'citations': ('parts', 'citations'),
      'target-notes': ('references', 'target_notes'),
      'meta': ('html', 'meta'),
      #'imagemap': ('html', 'imagemap'),
      'raw': ('misc', 'raw'),
      'include': ('misc', 'include'),
      'replace': ('misc', 'replace'),
      'unicode': ('misc', 'unicode_directive'),
      'class': ('misc', 'class_directive'),
      'role': ('misc', 'role'),
      'restructuredtext-test-directive': ('misc', 'directive_test_function'),}
"""Mapping of directive name to (module name, function name).  The directive
name is canonical & must be lowercase.  Language-dependent names are defined
in the ``language`` subpackage."""

_modules = {}
"""Cache of imported directive modules."""

_directives = {}
"""Cache of imported directive functions."""

def directive(directive_name, language_module, document):
    """
    Locate and return a directive function from its language-dependent name.
    If not found in the current language, check English.  Return None if the
    named directive cannot be found.
    """
    normname = directive_name.lower()
    messages = []
    msg_text = []
    if _directives.has_key(normname):
        return _directives[normname], messages
    canonicalname = None
    try:
        canonicalname = language_module.directives[normname]
    except AttributeError, error:
        msg_text.append('Problem retrieving directive entry from language '
                        'module %r: %s.' % (language_module, error))
    except KeyError:
        msg_text.append('No directive entry for "%s" in module "%s".'
                        % (directive_name, language_module.__name__))
    if not canonicalname:
        try:
            canonicalname = _fallback_language_module.directives[normname]
            msg_text.append('Using English fallback for directive "%s".'
                            % directive_name)
        except KeyError:
            msg_text.append('Trying "%s" as canonical directive name.'
                            % directive_name)
            # The canonical name should be an English name, but just in case:
            canonicalname = normname
    if msg_text:
        message = document.reporter.info(
            '\n'.join(msg_text), line=document.current_line)
        messages.append(message)
    try:
        modulename, functionname = _directive_registry[canonicalname]
    except KeyError:
        messages.append(document.reporter.error(
            'Directive "%s" not registered (canonical name "%s").'
            % (directive_name, canonicalname), line=document.current_line))
        return None, messages
    if _modules.has_key(modulename):
        module = _modules[modulename]
    else:
        try:
            module = __import__(modulename, globals(), locals())
        except ImportError, detail:
            messages.append(document.reporter.error(
                'Error importing directive module "%s" (directive "%s"):\n%s'
                % (modulename, directive_name, detail),
                line=document.current_line))
            return None, messages
    try:
        function = getattr(module, functionname)
        _directives[normname] = function
    except AttributeError:
        messages.append(document.reporter.error(
            'No function "%s" in module "%s" (directive "%s").'
            % (functionname, modulename, directive_name),
            line=document.current_line))
        return None, messages
    return function, messages

def register_directive(name, directive_function):
    """
    Register a nonstandard application-defined directive function.
    Language lookups are not needed for such functions.
    """
    _directives[name] = directive_function

def flag(argument):
    """
    Check for a valid flag option (no argument) and return ``None``.
    (Directive option conversion function.)

    Raise ``ValueError`` if an argument is found.
    """
    if argument and argument.strip():
        raise ValueError('no argument is allowed; "%s" supplied' % argument)
    else:
        return None

def unchanged_required(argument):
    """
    Return the argument text, unchanged.
    (Directive option conversion function.)

    Raise ``ValueError`` if no argument is found.
    """
    if argument is None:
        raise ValueError('argument required but none supplied')
    else:
        return argument  # unchanged!

def unchanged(argument):
    """
    Return the argument text, unchanged.
    (Directive option conversion function.)

    No argument implies empty string ("").
    """
    if argument is None:
        return u''
    else:
        return argument  # unchanged!

def path(argument):
    """
    Return the path argument unwrapped (with newlines removed).
    (Directive option conversion function.)

    Raise ``ValueError`` if no argument is found.
    """
    if argument is None:
        raise ValueError('argument required but none supplied')
    else:
        path = ''.join([s.strip() for s in argument.splitlines()])
        return path

def uri(argument):
    """
    Return the URI argument with whitespace removed.
    (Directive option conversion function.)

    Raise ``ValueError`` if no argument is found.
    """
    if argument is None:
        raise ValueError('argument required but none supplied')
    else:
        uri = ''.join(argument.split())
        return uri

def nonnegative_int(argument):
    """
    Check for a nonnegative integer argument; raise ``ValueError`` if not.
    (Directive option conversion function.)
    """
    value = int(argument)
    if value < 0:
        raise ValueError('negative value; must be positive or zero')
    return value

def class_option(argument):
    """
    Convert the argument into a list of ID-compatible strings and return it.
    (Directive option conversion function.)

    Raise ``ValueError`` if no argument is found.
    """
    if argument is None:
        raise ValueError('argument required but none supplied')
    names = argument.split()
    class_names = []
    for name in names:
        class_name = nodes.make_id(name)
        if not class_name:
            raise ValueError('cannot make "%s" into a class name' % name)
        class_names.append(class_name)
    return class_names

unicode_pattern = re.compile(
    r'(?:0x|x|\\x|U\+?|\\u)([0-9a-f]+)$|&#x([0-9a-f]+);$', re.IGNORECASE)

def unicode_code(code):
    r"""
    Convert a Unicode character code to a Unicode character.
    (Directive option conversion function.)

    Codes may be decimal numbers, hexadecimal numbers (prefixed by ``0x``,
    ``x``, ``\x``, ``U+``, ``u``, or ``\u``; e.g. ``U+262E``), or XML-style
    numeric character entities (e.g. ``☮``).  Other text remains as-is.

    Raise ValueError for illegal Unicode code values.
    """
    try:
        if code.isdigit():                  # decimal number
            return unichr(int(code))
        else:
            match = unicode_pattern.match(code)
            if match:                       # hex number
                value = match.group(1) or match.group(2)
                return unichr(int(value, 16))
            else:                           # other text
                return code
    except OverflowError, detail:
        raise ValueError('code too large (%s)' % detail)

def single_char_or_unicode(argument):
    """
    A single character is returned as-is.  Unicode characters codes are
    converted as in `unicode_code`.  (Directive option conversion function.)
    """
    char = unicode_code(argument)
    if len(char) > 1:
        raise ValueError('%r invalid; must be a single character or '
                         'a Unicode code' % char)
    return char

def single_char_or_whitespace_or_unicode(argument):
    """
    As with `single_char_or_unicode`, but "tab" and "space" are also supported.
    (Directive option conversion function.)
    """
    if argument == 'tab':
        char = '\t'
    elif argument == 'space':
        char = ' '
    else:
        char = single_char_or_unicode(argument)
    return char

def positive_int(argument):
    """
    Converts the argument into an integer.  Raises ValueError for negative,
    zero, or non-integer values.  (Directive option conversion function.)
    """
    value = int(argument)
    if value < 1:
        raise ValueError('negative or zero value; must be positive')
    return value

def positive_int_list(argument):
    """
    Converts a space- or comma-separated list of values into a Python list
    of integers.
    (Directive option conversion function.)

    Raises ValueError for non-positive-integer values.
    """
    if ',' in argument:
        entries = argument.split(',')
    else:
        entries = argument.split()
    return [positive_int(entry) for entry in entries]

def encoding(argument):
    """
    Verfies the encoding argument by lookup.
    (Directive option conversion function.)

    Raises ValueError for unknown encodings.
    """
    try:
        codecs.lookup(argument)
    except LookupError:
        raise ValueError('unknown encoding: "%s"' % argument)
    return argument

def choice(argument, values):
    """
    Directive option utility function, supplied to enable options whose
    argument must be a member of a finite set of possible values (must be
    lower case).  A custom conversion function must be written to use it.  For
    example::

        from docutils.parsers.rst import directives

        def yesno(argument):
            return directives.choice(argument, ('yes', 'no'))

    Raise ``ValueError`` if no argument is found or if the argument's value is
    not valid (not an entry in the supplied list).
    """
    try:
        value = argument.lower().strip()
    except AttributeError:
        raise ValueError('must supply an argument; choose from %s'
                         % format_values(values))
    if value in values:
        return value
    else:
        raise ValueError('"%s" unknown; choose from %s'
                         % (argument, format_values(values)))

def format_values(values):
    return '%s, or "%s"' % (', '.join(['"%s"' % s for s in values[:-1]]),
                            values[-1])
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/misc.py���������������������������0000644�0001750�0001750�00000035670�10322366260�026557� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Authors: David Goodger, Dethe Elza
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3129 $
# Date: $Date: 2005-03-26 17:21:28 +0100 (Sat, 26 Mar 2005) $
# Copyright: This module has been placed in the public domain.

"""Miscellaneous directives."""

__docformat__ = 'reStructuredText'

import sys
import os.path
import re
from docutils import io, nodes, statemachine, utils
from docutils.parsers.rst import directives, roles, states
from docutils.transforms import misc

try:
    import urllib2
except ImportError:
    urllib2 = None


def include(name, arguments, options, content, lineno,
            content_offset, block_text, state, state_machine):
    """Include a reST file as part of the content of this reST file."""
    if not state.document.settings.file_insertion_enabled:
        warning = state_machine.reporter.warning(
              '"%s" directive disabled.' % name,
              nodes.literal_block(block_text, block_text), line=lineno)
        return [warning]
    source = state_machine.input_lines.source(
        lineno - state_machine.input_offset - 1)
    source_dir = os.path.dirname(os.path.abspath(source))
    path = directives.path(arguments[0])
    path = os.path.normpath(os.path.join(source_dir, path))
    path = utils.relative_path(None, path)
    encoding = options.get('encoding', state.document.settings.input_encoding)
    try:
        state.document.settings.record_dependencies.add(path)
        include_file = io.FileInput(
            source_path=path, encoding=encoding,
            error_handler=state.document.settings.input_encoding_error_handler,
            handle_io_errors=None)
    except IOError, error:
        severe = state_machine.reporter.severe(
              'Problems with "%s" directive path:\n%s: %s.'
              % (name, error.__class__.__name__, error),
              nodes.literal_block(block_text, block_text), line=lineno)
        return [severe]
    try:
        include_text = include_file.read()
    except UnicodeError, error:
        severe = state_machine.reporter.severe(
              'Problem with "%s" directive:\n%s: %s'
              % (name, error.__class__.__name__, error),
              nodes.literal_block(block_text, block_text), line=lineno)
        return [severe]
    if options.has_key('literal'):
        literal_block = nodes.literal_block(include_text, include_text,
                                            source=path)
        literal_block.line = 1
        return literal_block
    else:
        include_lines = statemachine.string2lines(include_text,
                                                  convert_whitespace=1)
        state_machine.insert_input(include_lines, path)
        return []

include.arguments = (1, 0, 1)
include.options = {'literal': directives.flag,
                   'encoding': directives.encoding}

def raw(name, arguments, options, content, lineno,
        content_offset, block_text, state, state_machine):
    """
    Pass through content unchanged

    Content is included in output based on type argument

    Content may be included inline (content section of directive) or
    imported from a file or url.
    """
    print 2
    if ( not state.document.settings.raw_enabled
         or (not state.document.settings.file_insertion_enabled
             and (options.has_key('file') or options.has_key('url'))) ):
        warning = state_machine.reporter.warning(
              '"%s" directive disabled.' % name,
              nodes.literal_block(block_text, block_text), line=lineno)
        return [warning]
    attributes = {'format': ' '.join(arguments[0].lower().split())}
    encoding = options.get('encoding', state.document.settings.input_encoding)
    if content:
        if options.has_key('file') or options.has_key('url'):
            error = state_machine.reporter.error(
                  '"%s" directive may not both specify an external file and '
                  'have content.' % name,
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [error]
        text = '\n'.join(content)
    elif options.has_key('file'):
        if options.has_key('url'):
            error = state_machine.reporter.error(
                  'The "file" and "url" options may not be simultaneously '
                  'specified for the "%s" directive.' % name,
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [error]
        source_dir = os.path.dirname(
            os.path.abspath(state.document.current_source))
        path = os.path.normpath(os.path.join(source_dir, options['file']))
        path = utils.relative_path(None, path)
        try:
            state.document.settings.record_dependencies.add(path)
            raw_file = io.FileInput(
                source_path=path, encoding=encoding,
                error_handler=state.document.settings.input_encoding_error_handler,
                handle_io_errors=None)
        except IOError, error:
            severe = state_machine.reporter.severe(
                  'Problems with "%s" directive path:\n%s.' % (name, error),
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [severe]
        try:
            text = raw_file.read()
        except UnicodeError, error:
            severe = state_machine.reporter.severe(
                  'Problem with "%s" directive:\n%s: %s'
                  % (name, error.__class__.__name__, error),
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [severe]
        attributes['source'] = path
    elif options.has_key('url'):
        if not urllib2:
            severe = state_machine.reporter.severe(
                  'Problems with the "%s" directive and its "url" option: '
                  'unable to access the required functionality (from the '
                  '"urllib2" module).' % name,
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [severe]
        source = options['url']
        try:
            raw_text = urllib2.urlopen(source).read()
        except (urllib2.URLError, IOError, OSError), error:
            severe = state_machine.reporter.severe(
                  'Problems with "%s" directive URL "%s":\n%s.'
                  % (name, options['url'], error),
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [severe]
        raw_file = io.StringInput(
            source=raw_text, source_path=source, encoding=encoding,
            error_handler=state.document.settings.input_encoding_error_handler)
        try:
            text = raw_file.read()
        except UnicodeError, error:
            severe = state_machine.reporter.severe(
                  'Problem with "%s" directive:\n%s: %s'
                  % (name, error.__class__.__name__, error),
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [severe]
        attributes['source'] = source
    else:
        error = state_machine.reporter.warning(
            'The "%s" directive requires content; none supplied.' % (name),
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    raw_node = nodes.raw('', text, **attributes)
    return [raw_node]

raw.arguments = (1, 0, 1)
raw.options = {'file': directives.path,
               'url': directives.uri,
               'encoding': directives.encoding}
raw.content = 1

def replace(name, arguments, options, content, lineno,
            content_offset, block_text, state, state_machine):
    if not isinstance(state, states.SubstitutionDef):
        error = state_machine.reporter.error(
            'Invalid context: the "%s" directive can only be used within a '
            'substitution definition.' % (name),
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    text = '\n'.join(content)
    element = nodes.Element(text)
    if text:
        state.nested_parse(content, content_offset, element)
        if len(element) != 1 or not isinstance(element[0], nodes.paragraph):
            messages = []
            for node in element:
                if isinstance(node, nodes.system_message):
                    node['backrefs'] = []
                    messages.append(node)
            error = state_machine.reporter.error(
                'Error in "%s" directive: may contain a single paragraph '
                'only.' % (name), line=lineno)
            messages.append(error)
            return messages
        else:
            return element[0].children
    else:
        error = state_machine.reporter.error(
            'The "%s" directive is empty; content required.' % (name),
            line=lineno)
        return [error]

replace.content = 1

def unicode_directive(name, arguments, options, content, lineno,
                      content_offset, block_text, state, state_machine):
    r"""
    Convert Unicode character codes (numbers) to characters.  Codes may be
    decimal numbers, hexadecimal numbers (prefixed by ``0x``, ``x``, ``\x``,
    ``U+``, ``u``, or ``\u``; e.g. ``U+262E``), or XML-style numeric character
    entities (e.g. ``☮``).  Text following ".." is a comment and is
    ignored.  Spaces are ignored, and any other text remains as-is.
    """
    if not isinstance(state, states.SubstitutionDef):
        error = state_machine.reporter.error(
            'Invalid context: the "%s" directive can only be used within a '
            'substitution definition.' % (name),
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    substitution_definition = state_machine.node
    if options.has_key('trim'):
        substitution_definition.attributes['ltrim'] = 1
        substitution_definition.attributes['rtrim'] = 1
    if options.has_key('ltrim'):
        substitution_definition.attributes['ltrim'] = 1
    if options.has_key('rtrim'):
        substitution_definition.attributes['rtrim'] = 1
    codes = unicode_comment_pattern.split(arguments[0])[0].split()
    element = nodes.Element()
    for code in codes:
        try:
            decoded = directives.unicode_code(code)
        except ValueError, err:
            error = state_machine.reporter.error(
                'Invalid character code: %s\n%s: %s'
                % (code, err.__class__.__name__, err),
                nodes.literal_block(block_text, block_text), line=lineno)
            return [error]
        element += nodes.Text(decoded)
    return element.children

unicode_directive.arguments = (1, 0, 1)
unicode_directive.options = {'trim': directives.flag,
                             'ltrim': directives.flag,
                             'rtrim': directives.flag}
unicode_comment_pattern = re.compile(r'( |\n|^)\.\. ')

def class_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
    """
    Set a "class" attribute on the next element.
    A "pending" element is inserted, and a transform does the work later.
    """
    try:
        class_value = directives.class_option(arguments[0])
    except ValueError:
        error = state_machine.reporter.error(
            'Invalid class attribute value for "%s" directive: "%s".'
            % (name, arguments[0]),
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    pending = nodes.pending(misc.ClassAttribute,
                            {'class': class_value, 'directive': name},
                            block_text)
    state_machine.document.note_pending(pending)
    return [pending]

class_directive.arguments = (1, 0, 1)
class_directive.content = 1

role_arg_pat = re.compile(r'(%s)\s*(\(\s*(%s)\s*\)\s*)?$'
                          % ((states.Inliner.simplename,) * 2))
def role(name, arguments, options, content, lineno,
         content_offset, block_text, state, state_machine):
    """Dynamically create and register a custom interpreted text role."""
    if content_offset > lineno or not content:
        error = state_machine.reporter.error(
            '"%s" directive requires arguments on the first line.'
            % name, nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    args = content[0]
    match = role_arg_pat.match(args)
    if not match:
        error = state_machine.reporter.error(
            '"%s" directive arguments not valid role names: "%s".'
            % (name, args), nodes.literal_block(block_text, block_text),
            line=lineno)
        return [error]
    new_role_name = match.group(1)
    base_role_name = match.group(3)
    messages = []
    if base_role_name:
        base_role, messages = roles.role(
            base_role_name, state_machine.language, lineno, state.reporter)
        if base_role is None:
            error = state.reporter.error(
                'Unknown interpreted text role "%s".' % base_role_name,
                nodes.literal_block(block_text, block_text), line=lineno)
            return messages + [error]
    else:
        base_role = roles.generic_custom_role
    assert not hasattr(base_role, 'arguments'), (
        'Supplemental directive arguments for "%s" directive not supported'
        '(specified by "%r" role).' % (name, base_role))
    try:
        (arguments, options, content, content_offset) = (
            state.parse_directive_block(content[1:], content_offset, base_role,
                                        option_presets={}))
    except states.MarkupError, detail:
        error = state_machine.reporter.error(
            'Error in "%s" directive:\n%s.' % (name, detail),
            nodes.literal_block(block_text, block_text), line=lineno)
        return messages + [error]
    if not options.has_key('class'):
        try:
            options['class'] = directives.class_option(new_role_name)
        except ValueError, detail:
            error = state_machine.reporter.error(
                'Invalid argument for "%s" directive:\n%s.'
                % (name, detail),
                nodes.literal_block(block_text, block_text), line=lineno)
            return messages + [error]
    role = roles.CustomRole(new_role_name, base_role, options, content)
    roles.register_local_role(new_role_name, role)
    return messages

role.content = 1

def directive_test_function(name, arguments, options, content, lineno,
                            content_offset, block_text, state, state_machine):
    """This directive is useful only for testing purposes."""
    if content:
        text = '\n'.join(content)
        info = state_machine.reporter.info(
            'Directive processed. Type="%s", arguments=%r, options=%r, '
            'content:' % (name, arguments, options),
            nodes.literal_block(text, text), line=lineno)
    else:
        info = state_machine.reporter.info(
            'Directive processed. Type="%s", arguments=%r, options=%r, '
            'content: None' % (name, arguments, options), line=lineno)
    return [info]

directive_test_function.arguments = (0, 1, 1)
directive_test_function.options = {'option': directives.unchanged_required}
directive_test_function.content = 1
������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/body.py���������������������������0000644�0001750�0001750�00000015030�10322224711�026537� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@python.org
# Revision: $Revision: 3206 $
# Date: $Date: 2005-04-12 01:16:11 +0200 (Tue, 12 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
Directives for additional body elements.

See `docutils.parsers.rst.directives` for API details.
"""

__docformat__ = 'reStructuredText'


import sys
from docutils import nodes
from docutils.parsers.rst import directives
from docutils.parsers.rst.roles import set_classes

              
def topic(name, arguments, options, content, lineno,
          content_offset, block_text, state, state_machine,
          node_class=nodes.topic):
    if not (state_machine.match_titles
            or isinstance(state_machine.node, nodes.sidebar)):
        error = state_machine.reporter.error(
              'The "%s" directive may not be used within topics '
              'or body elements.' % name,
              nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text),
            line=lineno)
        return [warning]
    title_text = arguments[0]
    textnodes, messages = state.inline_text(title_text, lineno)
    titles = [nodes.title(title_text, '', *textnodes)]
    # sidebar uses this code
    if options.has_key('subtitle'):
        textnodes, more_messages = state.inline_text(options['subtitle'],
                                                     lineno)
        titles.append(nodes.subtitle(options['subtitle'], '', *textnodes))
        messages.extend(more_messages)
    text = '\n'.join(content)
    node = node_class(text, *(titles + messages))
    node['classes'] += options.get('class', [])
    if text:
        state.nested_parse(content, content_offset, node)
    return [node]

topic.arguments = (1, 0, 1)
topic.options = {'class': directives.class_option}
topic.content = 1

def sidebar(name, arguments, options, content, lineno,
            content_offset, block_text, state, state_machine):
    if isinstance(state_machine.node, nodes.sidebar):
        error = state_machine.reporter.error(
              'The "%s" directive may not be used within a sidebar element.'
              % name, nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    return topic(name, arguments, options, content, lineno,
                 content_offset, block_text, state, state_machine,
                 node_class=nodes.sidebar)

sidebar.arguments = (1, 0, 1)
sidebar.options = {'subtitle': directives.unchanged_required,
                   'class': directives.class_option}
sidebar.content = 1

def line_block(name, arguments, options, content, lineno,
               content_offset, block_text, state, state_machine):
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text), line=lineno)
        return [warning]
    block = nodes.line_block(classes=options.get('class', []))
    node_list = [block]
    for line_text in content:
        text_nodes, messages = state.inline_text(line_text.strip(),
                                                 lineno + content_offset)
        line = nodes.line(line_text, '', *text_nodes)
        if line_text.strip():
            line.indent = len(line_text) - len(line_text.lstrip())
        block += line
        node_list.extend(messages)
        content_offset += 1
    state.nest_line_block_lines(block)
    return node_list

line_block.options = {'class': directives.class_option}
line_block.content = 1

def parsed_literal(name, arguments, options, content, lineno,
                   content_offset, block_text, state, state_machine):
    set_classes(options)
    return block(name, arguments, options, content, lineno,
                 content_offset, block_text, state, state_machine,
                 node_class=nodes.literal_block)

parsed_literal.options = {'class': directives.class_option}
parsed_literal.content = 1

def block(name, arguments, options, content, lineno,
          content_offset, block_text, state, state_machine, node_class):
    if not content:
        warning = state_machine.reporter.warning(
            'Content block expected for the "%s" directive; none found.'
            % name, nodes.literal_block(block_text, block_text), line=lineno)
        return [warning]
    text = '\n'.join(content)
    text_nodes, messages = state.inline_text(text, lineno)
    node = node_class(text, '', *text_nodes, **options)
    node.line = content_offset + 1
    return [node] + messages

def rubric(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    rubric_text = arguments[0]
    textnodes, messages = state.inline_text(rubric_text, lineno)
    rubric = nodes.rubric(rubric_text, '', *textnodes, **options)
    return [rubric] + messages

rubric.arguments = (1, 0, 1)
rubric.options = {'class': directives.class_option}

def epigraph(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    block_quote, messages = state.block_quote(content, content_offset)
    block_quote['classes'].append('epigraph')
    return [block_quote] + messages

epigraph.content = 1

def highlights(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    block_quote, messages = state.block_quote(content, content_offset)
    block_quote['classes'].append('highlights')
    return [block_quote] + messages

highlights.content = 1

def pull_quote(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    block_quote, messages = state.block_quote(content, content_offset)
    block_quote['classes'].append('pull-quote')
    return [block_quote] + messages

pull_quote.content = 1

def compound(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    text = '\n'.join(content)
    if not text:
        error = state_machine.reporter.error(
            'The "%s" directive is empty; content required.' % name,
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    node = nodes.compound(text)
    node['classes'] += options.get('class', [])
    state.nested_parse(content, content_offset, node)
    return [node]

compound.options = {'class': directives.class_option}
compound.content = 1
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/references.py���������������������0000644�0001750�0001750�00000001300�10322224711�027716� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger, Dmitry Jemerov
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 856 $
# Date: $Date: 2002-10-24 03:01:53 +0200 (Thu, 24 Oct 2002) $
# Copyright: This module has been placed in the public domain.

"""
Directives for references and targets.
"""

__docformat__ = 'reStructuredText'

from docutils import nodes
from docutils.transforms import references


def target_notes(name, arguments, options, content, lineno,
                 content_offset, block_text, state, state_machine):
    """Target footnote generation."""
    pending = nodes.pending(references.TargetNotes)
    state_machine.document.note_pending(pending)
    nodelist = [pending]
    return nodelist
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/admonitions.py��������������������0000644�0001750�0001750�00000004420�10322224711�030127� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3155 $
# Date: $Date: 2005-04-02 23:57:06 +0200 (Sat, 02 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
Admonition directives.
"""

__docformat__ = 'reStructuredText'


from docutils.parsers.rst import states, directives
from docutils import nodes


def make_admonition(node_class, name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
    if not content:
        error = state_machine.reporter.error(
            'The "%s" admonition is empty; content required.' % (name),
            nodes.literal_block(block_text, block_text), line=lineno)
        return [error]
    text = '\n'.join(content)
    admonition_node = node_class(text)
    if arguments:
        title_text = arguments[0]
        textnodes, messages = state.inline_text(title_text, lineno)
        admonition_node += nodes.title(title_text, '', *textnodes)
        admonition_node += messages
        if options.has_key('class'):
            classes = options['class']
        else:
            classes = ['admonition-' + nodes.make_id(title_text)]
        admonition_node['classes'] += classes
    state.nested_parse(content, content_offset, admonition_node)
    return [admonition_node]

def admonition(*args):
    return make_admonition(nodes.admonition, *args)

admonition.arguments = (1, 0, 1)
admonition.options = {'class': directives.class_option}
admonition.content = 1

def attention(*args):
    return make_admonition(nodes.attention, *args)

attention.content = 1

def caution(*args):
    return make_admonition(nodes.caution, *args)

caution.content = 1

def danger(*args):
    return make_admonition(nodes.danger, *args)

danger.content = 1

def error(*args):
    return make_admonition(nodes.error, *args)

error.content = 1

def hint(*args):
    return make_admonition(nodes.hint, *args)

hint.content = 1

def important(*args):
    return make_admonition(nodes.important, *args)

important.content = 1

def note(*args):
    return make_admonition(nodes.note, *args)

note.content = 1

def tip(*args):
    return make_admonition(nodes.tip, *args)

tip.content = 1

def warning(*args):
    return make_admonition(nodes.warning, *args)

warning.content = 1
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/html.py���������������������������0000644�0001750�0001750�00000006711�10322224711�026554� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3038 $
# Date: $Date: 2005-03-14 17:16:57 +0100 (Mon, 14 Mar 2005) $
# Copyright: This module has been placed in the public domain.

"""
Directives for typically HTML-specific constructs.
"""

__docformat__ = 'reStructuredText'

import sys
from docutils import nodes, utils
from docutils.parsers.rst import states
from docutils.transforms import components


def meta(name, arguments, options, content, lineno,
         content_offset, block_text, state, state_machine):
    node = nodes.Element()
    if content:
        new_line_offset, blank_finish = state.nested_list_parse(
              content, content_offset, node, initial_state='MetaBody',
              blank_finish=1, state_machine_kwargs=metaSMkwargs)
        if (new_line_offset - content_offset) != len(content):
            # incomplete parse of block?
            error = state_machine.reporter.error(
                'Invalid meta directive.',
                nodes.literal_block(block_text, block_text), line=lineno)
            node += error
    else:
        error = state_machine.reporter.error(
            'Empty meta directive.',
            nodes.literal_block(block_text, block_text), line=lineno)
        node += error
    return node.children

meta.content = 1

def imagemap(name, arguments, options, content, lineno,
             content_offset, block_text, state, state_machine):
    return []


class MetaBody(states.SpecializedBody):

    class meta(nodes.Special, nodes.PreBibliographic, nodes.Element):
        """HTML-specific "meta" element."""
        pass

    def field_marker(self, match, context, next_state):
        """Meta element."""
        node, blank_finish = self.parsemeta(match)
        self.parent += node
        return [], next_state, []

    def parsemeta(self, match):
        name = self.parse_field_marker(match)
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end())
        node = self.meta()
        pending = nodes.pending(components.Filter,
                                {'component': 'writer',
                                 'format': 'html',
                                 'nodes': [node]})
        node['content'] = ' '.join(indented)
        if not indented:
            line = self.state_machine.line
            msg = self.reporter.info(
                  'No content for meta tag "%s".' % name,
                  nodes.literal_block(line, line),
                  line=self.state_machine.abs_line_number())
            return msg, blank_finish
        tokens = name.split()
        try:
            attname, val = utils.extract_name_value(tokens[0])[0]
            node[attname.lower()] = val
        except utils.NameValueError:
            node['name'] = tokens[0]
        for token in tokens[1:]:
            try:
                attname, val = utils.extract_name_value(token)[0]
                node[attname.lower()] = val
            except utils.NameValueError, detail:
                line = self.state_machine.line
                msg = self.reporter.error(
                      'Error parsing meta tag attribute "%s": %s.'
                      % (token, detail), nodes.literal_block(line, line),
                      line=self.state_machine.abs_line_number())
                return msg, blank_finish
        self.document.note_pending(pending)
        return pending, blank_finish


metaSMkwargs = {'state_classes': (MetaBody,)}
�������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/directives/images.py�������������������������0000644�0001750�0001750�00000013423�10322224711�027053� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3347 $
# Date: $Date: 2005-05-18 20:17:33 +0200 (Wed, 18 May 2005) $
# Copyright: This module has been placed in the public domain.

"""
Directives for figures and simple images.
"""

__docformat__ = 'reStructuredText'


import sys
from docutils import nodes, utils
from docutils.parsers.rst import directives, states
from docutils.nodes import fully_normalize_name
from docutils.parsers.rst.roles import set_classes

try:
    import Image                        # PIL
except ImportError:
    Image = None

align_h_values = ('left', 'center', 'right')
align_v_values = ('top', 'middle', 'bottom')
align_values = align_v_values + align_h_values

def align(argument):
    return directives.choice(argument, align_values)

def image(name, arguments, options, content, lineno,
          content_offset, block_text, state, state_machine):
    if options.has_key('align'):
        # check for align_v values only
        if isinstance(state, states.SubstitutionDef):
            if options['align'] not in align_v_values:
                error = state_machine.reporter.error(
                    'Error in "%s" directive: "%s" is not a valid value for '
                    'the "align" option within a substitution definition.  '
                    'Valid values for "align" are: "%s".'
                    % (name, options['align'], '", "'.join(align_v_values)),
                    nodes.literal_block(block_text, block_text), line=lineno)
                return [error]
        elif options['align'] not in align_h_values:
            error = state_machine.reporter.error(
                'Error in "%s" directive: "%s" is not a valid value for '
                'the "align" option.  Valid values for "align" are: "%s".'
                % (name, options['align'], '", "'.join(align_h_values)),
                nodes.literal_block(block_text, block_text), line=lineno)
            return [error]
    messages = []
    reference = directives.uri(arguments[0])
    options['uri'] = reference
    reference_node = None
    if options.has_key('target'):
        block = states.escape2null(options['target']).splitlines()
        block = [line for line in block]
        target_type, data = state.parse_target(block, block_text, lineno)
        if target_type == 'refuri':
            reference_node = nodes.reference(refuri=data)
        elif target_type == 'refname':
            reference_node = nodes.reference(refname=data,
                name=fully_normalize_name(options['target']))
            state.document.note_refname(reference_node)
        else:                           # malformed target
            messages.append(data)       # data is a system message
        del options['target']
    set_classes(options)
    image_node = nodes.image(block_text, **options)
    if reference_node:
        reference_node += image_node
        return messages + [reference_node]
    else:
        return messages + [image_node]

image.arguments = (1, 0, 1)
image.options = {'alt': directives.unchanged,
                 'height': directives.nonnegative_int,
                 'width': directives.nonnegative_int,
                 'scale': directives.nonnegative_int,
                 'align': align,
                 'target': directives.unchanged_required,
                 'class': directives.class_option}

def figure_align(argument):
    return directives.choice(argument, align_h_values)

def figure(name, arguments, options, content, lineno,
           content_offset, block_text, state, state_machine):
    figwidth = options.setdefault('figwidth')
    figclasses = options.setdefault('figclass')
    align = options.setdefault('align')
    del options['figwidth']
    del options['figclass']
    del options['align']
    (image_node,) = image(name, arguments, options, content, lineno,
                         content_offset, block_text, state, state_machine)
    if isinstance(image_node, nodes.system_message):
        return [image_node]
    figure_node = nodes.figure('', image_node)
    if figwidth == 'image':
        if Image and state.document.settings.file_insertion_enabled:
            # PIL doesn't like Unicode paths:
            try:
                i = Image.open(str(image_node['uri']))
            except (IOError, UnicodeError):
                pass
            else:
                state.document.settings.record_dependencies.add(image_node['uri'])
                figure_node['width'] = i.size[0]
    elif figwidth is not None:
        figure_node['width'] = figwidth
    if figclasses:
        figure_node['classes'] += figclasses
    if align:
        figure_node['align'] = align
    if content:
        node = nodes.Element()          # anonymous container for parsing
        state.nested_parse(content, content_offset, node)
        first_node = node[0]
        if isinstance(first_node, nodes.paragraph):
            caption = nodes.caption(first_node.rawsource, '',
                                    *first_node.children)
            figure_node += caption
        elif not (isinstance(first_node, nodes.comment)
                  and len(first_node) == 0):
            error = state_machine.reporter.error(
                  'Figure caption must be a paragraph or empty comment.',
                  nodes.literal_block(block_text, block_text), line=lineno)
            return [figure_node, error]
        if len(node) > 1:
            figure_node += nodes.legend('', *node[1:])
    return [figure_node]

def figwidth_value(argument):
    if argument.lower() == 'image':
        return 'image'
    else:
        return directives.nonnegative_int(argument)

figure.arguments = (1, 0, 1)
figure.options = {'figwidth': figwidth_value,
                  'figclass': directives.class_option}
figure.options.update(image.options)
figure.options['align'] = figure_align
figure.content = 1
���������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/__init__.py����������������������������������0000644�0001750�0001750�00000014176�10322224711�025212� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3171 $
# Date: $Date: 2005-04-05 17:26:16 +0200 (Tue, 05 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
This is ``docutils.parsers.rst`` package. It exports a single class, `Parser`,
the reStructuredText parser.


Usage
=====

1. Create a parser::

       parser = docutils.parsers.rst.Parser()

   Several optional arguments may be passed to modify the parser's behavior.
   Please see `Customizing the Parser`_ below for details.

2. Gather input (a multi-line string), by reading a file or the standard
   input::

       input = sys.stdin.read()

3. Create a new empty `docutils.nodes.document` tree::

       document = docutils.utils.new_document(source, settings)

   See `docutils.utils.new_document()` for parameter details.

4. Run the parser, populating the document tree::

       parser.parse(input, document)


Parser Overview
===============

The reStructuredText parser is implemented as a state machine, examining its
input one line at a time. To understand how the parser works, please first
become familiar with the `docutils.statemachine` module, then see the
`states` module.


Customizing the Parser
----------------------

Anything that isn't already customizable is that way simply because that type
of customizability hasn't been implemented yet.  Patches welcome!

When instantiating an object of the `Parser` class, two parameters may be
passed: ``rfc2822`` and ``inliner``.  Pass ``rfc2822=1`` to enable an initial
RFC-2822 style header block, parsed as a "field_list" element (with "class"
attribute set to "rfc2822").  Currently this is the only body-level element
which is customizable without subclassing.  (Tip: subclass `Parser` and change
its "state_classes" and "initial_state" attributes to refer to new classes.
Contact the author if you need more details.)

The ``inliner`` parameter takes an instance of `states.Inliner` or a subclass.
It handles inline markup recognition.  A common extension is the addition of
further implicit hyperlinks, like "RFC 2822".  This can be done by subclassing
`states.Inliner`, adding a new method for the implicit markup, and adding a
``(pattern, method)`` pair to the "implicit_dispatch" attribute of the
subclass.  See `states.Inliner.implicit_inline()` for details.  Explicit
inline markup can be customized in a `states.Inliner` subclass via the
``patterns.initial`` and ``dispatch`` attributes (and new methods as
appropriate).
"""

__docformat__ = 'reStructuredText'


import docutils.parsers
import docutils.statemachine
from docutils.parsers.rst import states
from docutils import frontend


class Parser(docutils.parsers.Parser):

    """The reStructuredText parser."""

    supported = ('restructuredtext', 'rst', 'rest', 'restx', 'rtxt', 'rstx')
    """Aliases this parser supports."""

    settings_spec = (
        'reStructuredText Parser Options',
        None,
        (('Recognize and link to standalone PEP references (like "PEP 258").',
          ['--pep-references'],
          {'action': 'store_true', 'validator': frontend.validate_boolean}),
         ('Base URL for PEP references '
          '(default "http://www.python.org/peps/").',
          ['--pep-base-url'],
          {'metavar': '<URL>', 'default': 'http://www.python.org/peps/',
           'validator': frontend.validate_url_trailing_slash}),
         ('Recognize and link to standalone RFC references (like "RFC 822").',
          ['--rfc-references'],
          {'action': 'store_true', 'validator': frontend.validate_boolean}),
         ('Base URL for RFC references (default "http://www.faqs.org/rfcs/").',
          ['--rfc-base-url'],
          {'metavar': '<URL>', 'default': 'http://www.faqs.org/rfcs/',
           'validator': frontend.validate_url_trailing_slash}),
         ('Set number of spaces for tab expansion (default 8).',
          ['--tab-width'],
          {'metavar': '<width>', 'type': 'int', 'default': 8}),
         ('Remove spaces before footnote references.',
          ['--trim-footnote-reference-space'],
          {'action': 'store_true', 'validator': frontend.validate_boolean}),
         ('Leave spaces before footnote references.',
          ['--leave-footnote-reference-space'],
          {'action': 'store_false', 'dest': 'trim_footnote_reference_space',
           'validator': frontend.validate_boolean}),
         ('Disable directives that insert the contents of external file '
          '("include" & "raw"); replaced with a "warning" system message.',
          ['--no-file-insertion'],
          {'action': 'store_false', 'default': 1,
           'dest': 'file_insertion_enabled'}),
         ('Enable directives that insert the contents of external file '
          '("include" & "raw").  Enabled by default.',
          ['--file-insertion-enabled'],
          {'action': 'store_true', 'dest': 'file_insertion_enabled'}),
         ('Disable the "raw" directives; replaced with a "warning" '
          'system message.',
          ['--no-raw'],
          {'action': 'store_false', 'default': 1, 'dest': 'raw_enabled'}),
         ('Enable the "raw" directive.  Enabled by default.',
          ['--raw-enabled'],
          {'action': 'store_true', 'dest': 'raw_enabled'}),))

    config_section = 'restructuredtext parser'
    config_section_dependencies = ('parsers',)

    def __init__(self, rfc2822=None, inliner=None):
        if rfc2822:
            self.initial_state = 'RFC2822Body'
        else:
            self.initial_state = 'Body'
        self.state_classes = states.state_classes
        self.inliner = inliner

    def parse(self, inputstring, document):
        """Parse `inputstring` and populate `document`, a document tree."""
        self.setup_parse(inputstring, document)
        self.statemachine = states.RSTStateMachine(
              state_classes=self.state_classes,
              initial_state=self.initial_state,
              debug=document.reporter.debug_flag)
        inputlines = docutils.statemachine.string2lines(
              inputstring, tab_width=document.settings.tab_width,
              convert_whitespace=1)
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        self.finish_parse()
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/roman.py�������������������������������������0000644�0001750�0001750�00000005177�10172235404�024574� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������"""Convert to and from Roman numerals"""

__author__ = "Mark Pilgrim (f8dy@diveintopython.org)"
__version__ = "1.4"
__date__ = "8 August 2001"
__copyright__ = """Copyright (c) 2001 Mark Pilgrim

This program is part of "Dive Into Python", a free Python tutorial for
experienced programmers.  Visit http://diveintopython.org/ for the
latest version.

This program is free software; you can redistribute it and/or modify
it under the terms of the Python 2.1.1 license, available at
http://www.python.org/2.1.1/license.html
"""

import re

#Define exceptions
class RomanError(Exception): pass
class OutOfRangeError(RomanError): pass
class NotIntegerError(RomanError): pass
class InvalidRomanNumeralError(RomanError): pass

#Define digit mapping
romanNumeralMap = (('M',  1000),
                   ('CM', 900),
                   ('D',  500),
                   ('CD', 400),
                   ('C',  100),
                   ('XC', 90),
                   ('L',  50),
                   ('XL', 40),
                   ('X',  10),
                   ('IX', 9),
                   ('V',  5),
                   ('IV', 4),
                   ('I',  1))

def toRoman(n):
    """convert integer to Roman numeral"""
    if not (0 < n < 5000):
        raise OutOfRangeError, "number out of range (must be 1..4999)"
    if int(n) <> n:
        raise NotIntegerError, "decimals can not be converted"

    result = ""
    for numeral, integer in romanNumeralMap:
        while n >= integer:
            result += numeral
            n -= integer
    return result

#Define pattern to detect valid Roman numerals
romanNumeralPattern = re.compile("""
    ^                   # beginning of string
    M{0,4}              # thousands - 0 to 4 M's
    (CM|CD|D?C{0,3})    # hundreds - 900 (CM), 400 (CD), 0-300 (0 to 3 C's),
                        #            or 500-800 (D, followed by 0 to 3 C's)
    (XC|XL|L?X{0,3})    # tens - 90 (XC), 40 (XL), 0-30 (0 to 3 X's),
                        #        or 50-80 (L, followed by 0 to 3 X's)
    (IX|IV|V?I{0,3})    # ones - 9 (IX), 4 (IV), 0-3 (0 to 3 I's),
                        #        or 5-8 (V, followed by 0 to 3 I's)
    $                   # end of string
    """ ,re.VERBOSE)

def fromRoman(s):
    """convert Roman numeral to integer"""
    if not s:
        raise InvalidRomanNumeralError, 'Input can not be blank'
    if not romanNumeralPattern.search(s):
        raise InvalidRomanNumeralError, 'Invalid Roman numeral: %s' % s

    result = 0
    index = 0
    for numeral, integer in romanNumeralMap:
        while s[index:index+len(numeral)] == numeral:
            result += integer
            index += len(numeral)
    return result

�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/�����������������������������������0000755�0001750�0001750�00000000000�10447233610�025044� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/__init__.py������������������������0000644�0001750�0001750�00000001363�10322224711�027152� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# Internationalization details are documented in
# <http://docutils.sf.net/docs/howto/i18n.html>.

"""
This package contains modules for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'

_languages = {}

def get_language(language_code):
    if _languages.has_key(language_code):
        return _languages[language_code]
    try:
        module = __import__(language_code, globals(), locals())
    except ImportError:
        return None
    _languages[language_code] = module
    return module
�����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/sv.py������������������������������0000644�0001750�0001750�00000007425�10322224711�026050� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author:    Adam Chodorowski
# Contact:   chodorowski@users.sourceforge.net
# Revision:  $Revision: 3184 $
# Date:      $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Swedish language mappings for language-dependent features of reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      u'observera': 'attention',
      u'caution (translation required)': 'caution',
      u'fara': 'danger',
      u'fel': 'error',
      u'v\u00e4gledning': 'hint',
      u'viktigt': 'important',
      u'notera': 'note',
      u'tips': 'tip',
      u'varning': 'warning',
      u'admonition (translation required)': 'admonition',
      u'sidebar (translation required)': 'sidebar',
      u'\u00e4mne': 'topic',
      u'line-block (translation required)': 'line-block',
      u'parsed-literal (translation required)': 'parsed-literal',
      u'mellanrubrik': 'rubric',
      u'epigraph (translation required)': 'epigraph',
      u'highlights (translation required)': 'highlights',
      u'pull-quote (translation required)': 'pull-quote',
      u'compound (translation required)': 'compound',
      # u'fr\u00e5gor': 'questions',
      # NOTE: A bit long, but recommended by http://www.nada.kth.se/dataterm/:
      # u'fr\u00e5gor-och-svar': 'questions',
      # u'vanliga-fr\u00e5gor': 'questions',  
      u'table (translation required)': 'table',
      u'csv-table (translation required)': 'csv-table',
      u'list-table (translation required)': 'list-table',
      u'meta': 'meta',
      # u'bildkarta': 'imagemap',   # FIXME: Translation might be too literal.
      u'bild': 'image',
      u'figur': 'figure',
      u'inkludera': 'include',   
      u'r\u00e5': 'raw',            # FIXME: Translation might be too literal.
      u'ers\u00e4tt': 'replace', 
      u'unicode': 'unicode',
      u'class (translation required)': 'class',
      u'role (translation required)': 'role',
      u'inneh\u00e5ll': 'contents',
      u'sektionsnumrering': 'sectnum',
      u'target-notes (translation required)': 'target-notes',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      # u'fotnoter': 'footnotes',
      # u'citeringar': 'citations',
      }
"""Swedish name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
      u'abbreviation (translation required)': 'abbreviation',
      u'acronym (translation required)': 'acronym',
      u'index (translation required)': 'index',
      u'subscript (translation required)': 'subscript',
      u'superscript (translation required)': 'superscript',
      u'title-reference (translation required)': 'title-reference',
      u'pep-reference (translation required)': 'pep-reference',
      u'rfc-reference (translation required)': 'rfc-reference',
      u'emphasis (translation required)': 'emphasis',
      u'strong (translation required)': 'strong',
      u'literal (translation required)': 'literal',
      u'named-reference (translation required)': 'named-reference',
      u'anonymous-reference (translation required)': 'anonymous-reference',
      u'footnote-reference (translation required)': 'footnote-reference',
      u'citation-reference (translation required)': 'citation-reference',
      u'substitution-reference (translation required)': 'substitution-reference',
      u'target (translation required)': 'target',
      u'uri-reference (translation required)': 'uri-reference',
      u'r\u00e5': 'raw',}
"""Mapping of Swedish role names to canonical role names for interpreted text.
"""
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/de.py������������������������������0000644�0001750�0001750�00000006026�10322224711�026004� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Authors: Engelbert Gruber; Felix Wiemann
# Contact: grubert@users.sourceforge.net
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
German-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      'achtung': 'attention',
      'vorsicht': 'caution',
      'gefahr': 'danger',
      'fehler': 'error',
      'hinweis': 'hint',
      'wichtig': 'important',
      'notiz': 'note',
      'tipp': 'tip',
      'warnung': 'warning',
      'ermahnung': 'admonition',
      'kasten': 'sidebar',
      'seitenkasten': 'sidebar',
      'thema': 'topic',
      'zeilen-block': 'line-block',
      'parsed-literal (translation required)': 'parsed-literal',
      'rubrik': 'rubric',
      'epigraph': 'epigraph',
      'highlights (translation required)': 'highlights',
      'pull-quote (translation required)': 'pull-quote', # kasten too ?
      'zusammengesetzt': 'compound',
      'verbund': 'compound',
      #'fragen': 'questions',
      'tabelle': 'table',
      'csv-tabelle': 'csv-table',
      'list-table (translation required)': 'list-table',
      'meta': 'meta',
      #'imagemap': 'imagemap',
      'bild': 'image',
      'abbildung': 'figure',
      u'unver\xe4ndert': 'raw',
      u'roh': 'raw',
      u'einf\xfcgen': 'include',
      'ersetzung': 'replace',
      'ersetzen': 'replace',
      'ersetze': 'replace',
      'unicode': 'unicode',
      'klasse': 'class',
      'rolle': 'role',
      'inhalt': 'contents',
      'kapitel-nummerierung': 'sectnum',
      'abschnitts-nummerierung': 'sectnum',
      u'linkziel-fu\xdfnoten': 'target-notes',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #u'fu\xdfnoten': 'footnotes',
      #'zitate': 'citations',
      }
"""German name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
      u'abk\xfcrzung': 'abbreviation',
      'akronym': 'acronym',
      'index': 'index',
      'tiefgestellt': 'subscript',
      'hochgestellt': 'superscript',
      'titel-referenz': 'title-reference',
      'pep-referenz': 'pep-reference',
      'rfc-referenz': 'rfc-reference',
      'betonung': 'emphasis',
      'fett': 'strong',
      u'w\xf6rtlich': 'literal',
      'benannte-referenz': 'named-reference',
      'unbenannte-referenz': 'anonymous-reference',
      u'fu\xdfnoten-referenz': 'footnote-reference',
      'zitat-referenz': 'citation-reference',
      'ersetzungs-referenz': 'substitution-reference',
      'ziel': 'target',
      'uri-referenz': 'uri-reference',
      u'unver\xe4ndert': 'raw',
      u'roh': 'raw',}
"""Mapping of German role names to canonical role names for interpreted text.
"""
����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/zh_tw.py���������������������������0000644�0001750�0001750�00000011352�10322224711�026545� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Traditional Chinese language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      'attention (translation required)': 'attention',
      'caution (translation required)': 'caution',
      'danger (translation required)': 'danger',
      'error (translation required)': 'error',
      'hint (translation required)': 'hint',
      'important (translation required)': 'important',
      'note (translation required)': 'note',
      'tip (translation required)': 'tip',
      'warning (translation required)': 'warning',
      'admonition (translation required)': 'admonition',
      'sidebar (translation required)': 'sidebar',
      'topic (translation required)': 'topic',
      'line-block (translation required)': 'line-block',
      'parsed-literal (translation required)': 'parsed-literal',
      'rubric (translation required)': 'rubric',
      'epigraph (translation required)': 'epigraph',
      'highlights (translation required)': 'highlights',
      'pull-quote (translation required)': 'pull-quote',
      'compound (translation required)': 'compound',
      #'questions (translation required)': 'questions',
      'table (translation required)': 'table',
      'csv-table (translation required)': 'csv-table',
      'list-table (translation required)': 'list-table',
      #'qa (translation required)': 'questions',
      #'faq (translation required)': 'questions',
      'meta (translation required)': 'meta',
      #'imagemap (translation required)': 'imagemap',
      'image (translation required)': 'image',
      'figure (translation required)': 'figure',
      'include (translation required)': 'include',
      'raw (translation required)': 'raw',
      'replace (translation required)': 'replace',
      'unicode (translation required)': 'unicode',
      'class (translation required)': 'class',
      'role (translation required)': 'role',
      'contents (translation required)': 'contents',
      'sectnum (translation required)': 'sectnum',
      'section-numbering (translation required)': 'sectnum',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #'footnotes (translation required)': 'footnotes',
      #'citations (translation required)': 'citations',
      'target-notes (translation required)': 'target-notes',
      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""Traditional Chinese name to registered (in directives/__init__.py)
directive name mapping."""

roles = {
    # language-dependent: fixed
    'abbreviation (translation required)': 'abbreviation',
    'ab (translation required)': 'abbreviation',
    'acronym (translation required)': 'acronym',
    'ac (translation required)': 'acronym',
    'index (translation required)': 'index',
    'i (translation required)': 'index',
    'subscript (translation required)': 'subscript',
    'sub (translation required)': 'subscript',
    'superscript (translation required)': 'superscript',
    'sup (translation required)': 'superscript',
    'title-reference (translation required)': 'title-reference',
    'title (translation required)': 'title-reference',
    't (translation required)': 'title-reference',
    'pep-reference (translation required)': 'pep-reference',
    'pep (translation required)': 'pep-reference',
    'rfc-reference (translation required)': 'rfc-reference',
    'rfc (translation required)': 'rfc-reference',
    'emphasis (translation required)': 'emphasis',
    'strong (translation required)': 'strong',
    'literal (translation required)': 'literal',
    'named-reference (translation required)': 'named-reference',
    'anonymous-reference (translation required)': 'anonymous-reference',
    'footnote-reference (translation required)': 'footnote-reference',
    'citation-reference (translation required)': 'citation-reference',
    'substitution-reference (translation required)': 'substitution-reference',
    'target (translation required)': 'target',
    'uri-reference (translation required)': 'uri-reference',
    'uri (translation required)': 'uri-reference',
    'url (translation required)': 'uri-reference',
    'raw (translation required)': 'raw',}
"""Mapping of Traditional Chinese role names to canonical role names for
interpreted text."""
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/fi.py������������������������������0000644�0001750�0001750�00000006356�10322224711�026020� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Asko Soukka
# Contact: asko.soukka@iki.fi
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Finnish-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      u'huomio': u'attention',
      u'varo': u'caution',
      u'vaara': u'danger',
      u'virhe': u'error',
      u'vihje': u'hint',
      u't\u00e4rke\u00e4\u00e4': u'important',
      u'huomautus': u'note',
      u'neuvo': u'tip',
      u'varoitus': u'warning',
      u'kehotus': u'admonition',
      u'sivupalkki': u'sidebar',
      u'aihe': u'topic',
      u'rivi': u'line-block',
      u'tasalevyinen': u'parsed-literal',
      u'ohje': u'rubric',
      u'epigraafi': u'epigraph',
      u'kohokohdat': u'highlights',
      u'lainaus': u'pull-quote',
      u'taulukko': u'table',
      u'csv-taulukko': u'csv-table',
      u'list-table (translation required)': 'list-table',
      u'compound (translation required)': 'compound',
      #u'kysymykset': u'questions',
      u'meta': u'meta',
      #u'kuvakartta': u'imagemap',
      u'kuva': u'image',
      u'kaavio': u'figure',
      u'sis\u00e4llyt\u00e4': u'include',
      u'raaka': u'raw',
      u'korvaa': u'replace',
      u'unicode': u'unicode',
      u'luokka': u'class',
      u'rooli': u'role',
      u'sis\u00e4llys': u'contents',
      u'kappale': u'sectnum',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #u'alaviitteet': u'footnotes',
      #u'viitaukset': u'citations',
      u'target-notes (translation required)': u'target-notes'}
"""Finnish name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    # language-dependent: fixed
    u'lyhennys': u'abbreviation',
    u'akronyymi': u'acronym',
    u'kirjainsana': u'acronym',
    u'hakemisto': u'index',
    u'luettelo': u'index',
    u'alaindeksi': u'subscript',
    u'indeksi': u'subscript',
    u'yl\u00e4indeksi': u'superscript',
    u'title-reference (translation required)': u'title-reference',
    u'title (translation required)': u'title-reference',
    u'pep-reference (translation required)': u'pep-reference',
    u'rfc-reference (translation required)': u'rfc-reference',
    u'korostus': u'emphasis',
    u'vahvistus': u'strong',
    u'tasalevyinen': u'literal',
    u'named-reference (translation required)': u'named-reference',
    u'anonymous-reference (translation required)': u'anonymous-reference',
    u'footnote-reference (translation required)': u'footnote-reference',
    u'citation-reference (translation required)': u'citation-reference',
    u'substitution-reference (translation required)': u'substitution-reference',
    u'kohde': u'target',
    u'uri-reference (translation required)': u'uri-reference',
    u'raw (translation required)': 'raw',}
"""Mapping of Finnish role names to canonical role names for interpreted text.
"""
����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/en.py������������������������������0000644�0001750�0001750�00000006066�10322224711�026022� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
English-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      'attention': 'attention',
      'caution': 'caution',
      'danger': 'danger',
      'error': 'error',
      'hint': 'hint',
      'important': 'important',
      'note': 'note',
      'tip': 'tip',
      'warning': 'warning',
      'admonition': 'admonition',
      'sidebar': 'sidebar',
      'topic': 'topic',
      'line-block': 'line-block',
      'parsed-literal': 'parsed-literal',
      'rubric': 'rubric',
      'epigraph': 'epigraph',
      'highlights': 'highlights',
      'pull-quote': 'pull-quote',
      'compound': 'compound',
      #'questions': 'questions',
      'table': 'table',
      'csv-table': 'csv-table',
      'list-table': 'list-table',
      #'qa': 'questions',
      #'faq': 'questions',
      'meta': 'meta',
      #'imagemap': 'imagemap',
      'image': 'image',
      'figure': 'figure',
      'include': 'include',
      'raw': 'raw',
      'replace': 'replace',
      'unicode': 'unicode',
      'class': 'class',
      'role': 'role',
      'contents': 'contents',
      'sectnum': 'sectnum',
      'section-numbering': 'sectnum',
      'header': 'header',
      'footer': 'footer',
      #'footnotes': 'footnotes',
      #'citations': 'citations',
      'target-notes': 'target-notes',
      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""English name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    # language-dependent: fixed
    'abbreviation': 'abbreviation',
    'ab': 'abbreviation',
    'acronym': 'acronym',
    'ac': 'acronym',
    'index': 'index',
    'i': 'index',
    'subscript': 'subscript',
    'sub': 'subscript',
    'superscript': 'superscript',
    'sup': 'superscript',
    'title-reference': 'title-reference',
    'title': 'title-reference',
    't': 'title-reference',
    'pep-reference': 'pep-reference',
    'pep': 'pep-reference',
    'rfc-reference': 'rfc-reference',
    'rfc': 'rfc-reference',
    'emphasis': 'emphasis',
    'strong': 'strong',
    'literal': 'literal',
    'named-reference': 'named-reference',
    'anonymous-reference': 'anonymous-reference',
    'footnote-reference': 'footnote-reference',
    'citation-reference': 'citation-reference',
    'substitution-reference': 'substitution-reference',
    'target': 'target',
    'uri-reference': 'uri-reference',
    'uri': 'uri-reference',
    'url': 'uri-reference',
    'raw': 'raw',}
"""Mapping of English role names to canonical role names for interpreted text.
"""
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/eo.py������������������������������0000644�0001750�0001750�00000007040�10322224711�026014� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Marcelo Huerta San Martin
# Contact: richieadler@users.sourceforge.net
# Revision: $Revision: 3189 $
# Date: $Date: 2005-04-08 05:05:45 +0200 (Fri, 08 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Esperanto-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      u'atentu': 'attention',
      u'zorgu': 'caution',
      u'dangxero': 'danger',
      u'dan\u011dero': 'danger',
      u'eraro': 'error',
      u'spuro': 'hint',
      u'grava': 'important',
      u'noto': 'note',
      u'helpeto': 'tip',
      u'averto': 'warning',
      u'admono': 'admonition',
      u'flankteksto': 'sidebar',
      u'temo': 'topic',
      u'linea-bloko': 'line-block',
      u'analizota-literalo': 'parsed-literal',
      u'rubriko': 'rubric',
      u'epigrafo': 'epigraph',
      u'elstarajxoj': 'highlights',
      u'elstara\u0135oj': 'highlights',
      u'ekstera-citajxo': 'pull-quote',
      u'ekstera-cita\u0135o': 'pull-quote',
      u'kombinajxo': 'compound',
      u'kombina\u0135o': 'compound',
      #'questions': 'questions',
      #'qa': 'questions',
      #'faq': 'questions',
      u'tabelo': 'table',
      u'tabelo-vdk': 'csv-table', # "valoroj disigitaj per komoj"
      u'tabelo-csv': 'csv-table',
      u'tabelo-lista': 'list-table',
      u'meta': 'meta',
      #'imagemap': 'imagemap',
      u'bildo': 'image',
      u'figuro': 'figure',
      u'inkludi': 'include',
      u'senanaliza': 'raw',
      u'anstatauxi': 'replace',
      u'anstata\u016di': 'replace',
      u'unicode': 'unicode',
      u'klaso': 'class',
      u'rolo': 'role',
      u'enhavo': 'contents',
      u'seknum': 'sectnum',
      u'sekcia-numerado': 'sectnum',
      u'kapsekcio': 'header',
      u'piedsekcio': 'footer',
      #'footnotes': 'footnotes',
      #'citations': 'citations',
      u'celaj-notoj': 'target-notes',
      u'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""Esperanto name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    # language-dependent: fixed
    u'mallongigo': 'abbreviation',
    u'mall': 'abbreviation',
    u'komenclitero': 'acronym',
    u'kl': 'acronym',
    u'indekso': 'index',
    u'i': 'index',
    u'subskribo': 'subscript',
    u'sub': 'subscript',
    u'supraskribo': 'superscript',
    u'sup': 'superscript',
    u'titola-referenco': 'title-reference',
    u'titolo': 'title-reference',
    u't': 'title-reference',
    u'pep-referenco': 'pep-reference',
    u'pep': 'pep-reference',
    u'rfc-referenco': 'rfc-reference',
    u'rfc': 'rfc-reference',
    u'emfazo': 'emphasis',
    u'forta': 'strong',
    u'litera': 'literal',
    u'nomita-referenco': 'named-reference',
    u'nenomita-referenco': 'anonymous-reference',
    u'piednota-referenco': 'footnote-reference',
    u'citajxo-referenco': 'citation-reference',
    u'cita\u0135o-referenco': 'citation-reference',
    u'anstatauxa-referenco': 'substitution-reference',
    u'anstata\u016da-referenco': 'substitution-reference',
    u'celo': 'target',
    u'uri-referenco': 'uri-reference',
    u'uri': 'uri-reference',
    u'url': 'uri-reference',
    u'senanaliza': 'raw',
}
"""Mapping of Esperanto role names to canonical role names for interpreted text.
"""
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/cs.py������������������������������0000644�0001750�0001750�00000010675�10322224711�026026� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Marek Blaha
# Contact: mb@dat.cz
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Czech-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      u'pozor': 'attention',
      u'caution (translation required)': 'caution', # jak rozlisit caution a warning?
      u'nebezpe\u010D\u00ED': 'danger',
      u'chyba': 'error',
      u'rada': 'hint',
      u'd\u016Fle\u017Eit\u00E9': 'important',
      u'pozn\u00E1mka': 'note',
      u'tip (translation required)': 'tip',
      u'varov\u00E1n\u00ED': 'warning',
      u'admonition (translation required)': 'admonition',
      u'sidebar (translation required)': 'sidebar',
      u't\u00E9ma': 'topic',
      u'line-block (translation required)': 'line-block',
      u'parsed-literal (translation required)': 'parsed-literal',
      u'odd\u00EDl': 'rubric',
      u'moto': 'epigraph',
      u'highlights (translation required)': 'highlights',
      u'pull-quote (translation required)': 'pull-quote',
      u'compound (translation required)': 'compound',
      #'questions': 'questions',
      #'qa': 'questions',
      #'faq': 'questions',
      u'table (translation required)': 'table',
      u'csv-table (translation required)': 'csv-table',
      u'list-table (translation required)': 'list-table',
      u'meta (translation required)': 'meta',
      #'imagemap': 'imagemap',
      u'image (translation required)': 'image',   # obrazek
      u'figure (translation required)': 'figure', # a tady?
      u'include (translation required)': 'include',
      u'raw (translation required)': 'raw',
      u'replace (translation required)': 'replace',
      u'unicode (translation required)': 'unicode',
      u't\u0159\u00EDda': 'class',
      u'role (translation required)': 'role',
      u'obsah': 'contents',
      u'sectnum (translation required)': 'sectnum',
      u'section-numbering (translation required)': 'sectnum',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #'footnotes': 'footnotes',
      #'citations': 'citations',
      u'target-notes (translation required)': 'target-notes',
      u'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""Czech name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    # language-dependent: fixed
    u'abbreviation (translation required)': 'abbreviation',
    u'ab (translation required)': 'abbreviation',
    u'acronym (translation required)': 'acronym',
    u'ac (translation required)': 'acronym',
    u'index (translation required)': 'index',
    u'i (translation required)': 'index',
    u'subscript (translation required)': 'subscript',
    u'sub (translation required)': 'subscript',
    u'superscript (translation required)': 'superscript',
    u'sup (translation required)': 'superscript',
    u'title-reference (translation required)': 'title-reference',
    u'title (translation required)': 'title-reference',
    u't (translation required)': 'title-reference',
    u'pep-reference (translation required)': 'pep-reference',
    u'pep (translation required)': 'pep-reference',
    u'rfc-reference (translation required)': 'rfc-reference',
    u'rfc (translation required)': 'rfc-reference',
    u'emphasis (translation required)': 'emphasis',
    u'strong (translation required)': 'strong',
    u'literal (translation required)': 'literal',
    u'named-reference (translation required)': 'named-reference',
    u'anonymous-reference (translation required)': 'anonymous-reference',
    u'footnote-reference (translation required)': 'footnote-reference',
    u'citation-reference (translation required)': 'citation-reference',
    u'substitution-reference (translation required)': 'substitution-reference',
    u'target (translation required)': 'target',
    u'uri-reference (translation required)': 'uri-reference',
    u'uri (translation required)': 'uri-reference',
    u'url (translation required)': 'uri-reference',
    u'raw (translation required)': 'raw',}
"""Mapping of Czech role names to canonical role names for interpreted text.
"""
�������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/pt_br.py���������������������������0000644�0001750�0001750�00000007150�10322224711�026521� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Brazilian Portuguese-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      u'aten\u00E7\u00E3o': 'attention',
      'cuidado': 'caution',
      'perigo': 'danger',
      'erro': 'error',
      u'sugest\u00E3o': 'hint',
      'importante': 'important',
      'nota': 'note',
      'dica': 'tip',
      'aviso': 'warning',
      u'exorta\u00E7\u00E3o': 'admonition',
      'barra-lateral': 'sidebar',
      u't\u00F3pico': 'topic',
      'bloco-de-linhas': 'line-block',
      'literal-interpretado': 'parsed-literal',
      'rubrica': 'rubric',
      u'ep\u00EDgrafo': 'epigraph',
      'destaques': 'highlights',
      u'cita\u00E7\u00E3o-destacada': 'pull-quote',
      u'compound (translation required)': 'compound',
      #'perguntas': 'questions',
      #'qa': 'questions',
      #'faq': 'questions',
      u'table (translation required)': 'table',
      u'csv-table (translation required)': 'csv-table',
      u'list-table (translation required)': 'list-table',
      'meta': 'meta',
      #'imagemap': 'imagemap',
      'imagem': 'image',
      'figura': 'figure',
      u'inclus\u00E3o': 'include',
      'cru': 'raw',
      u'substitui\u00E7\u00E3o': 'replace',
      'unicode': 'unicode',
      'classe': 'class',
      'role (translation required)': 'role',
      u'\u00EDndice': 'contents',
      'numsec': 'sectnum',
      u'numera\u00E7\u00E3o-de-se\u00E7\u00F5es': 'sectnum',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #u'notas-de-rorap\u00E9': 'footnotes',
      #u'cita\u00E7\u00F5es': 'citations',
      u'links-no-rodap\u00E9': 'target-notes',
      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""Brazilian Portuguese name to registered (in directives/__init__.py)
directive name mapping."""

roles = {
    # language-dependent: fixed
    u'abbrevia\u00E7\u00E3o': 'abbreviation',
    'ab': 'abbreviation',
    u'acr\u00F4nimo': 'acronym',
    'ac': 'acronym',
    u'\u00EDndice-remissivo': 'index',
    'i': 'index',
    'subscrito': 'subscript',
    'sub': 'subscript',
    'sobrescrito': 'superscript',
    'sob': 'superscript',
    u'refer\u00EAncia-a-t\u00EDtulo': 'title-reference',
    u't\u00EDtulo': 'title-reference',
    't': 'title-reference',
    u'refer\u00EAncia-a-pep': 'pep-reference',
    'pep': 'pep-reference',
    u'refer\u00EAncia-a-rfc': 'rfc-reference',
    'rfc': 'rfc-reference',
    u'\u00EAnfase': 'emphasis',
    'forte': 'strong',
    'literal': 'literal',               # translation required?
    u'refer\u00EAncia-por-nome': 'named-reference',
    u'refer\u00EAncia-an\u00F4nima': 'anonymous-reference',
    u'refer\u00EAncia-a-nota-de-rodap\u00E9': 'footnote-reference',
    u'refer\u00EAncia-a-cita\u00E7\u00E3o': 'citation-reference',
    u'refer\u00EAncia-a-substitui\u00E7\u00E3o': 'substitution-reference',
    'alvo': 'target',
    u'refer\u00EAncia-a-uri': 'uri-reference',
    'uri': 'uri-reference',
    'url': 'uri-reference',
    'cru': 'raw',}
"""Mapping of Brazilian Portuguese role names to canonical role names
for interpreted text."""
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/fr.py������������������������������0000644�0001750�0001750�00000006573�10322224711�026032� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Authors: David Goodger; William Dode
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
French-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      u'attention': 'attention',
      u'pr\u00E9caution': 'caution',
      u'danger': 'danger',
      u'erreur': 'error',
      u'conseil': 'hint',
      u'important': 'important',
      u'note': 'note',
      u'astuce': 'tip',
      u'avertissement': 'warning',
      u'admonition': 'admonition',
      u'encadr\u00E9': 'sidebar',
      u'sujet': 'topic',
      u'bloc-textuel': 'line-block',
      u'bloc-interpr\u00E9t\u00E9': 'parsed-literal',
      u'code-interpr\u00E9t\u00E9': 'parsed-literal',
      u'intertitre': 'rubric',
      u'exergue': 'epigraph',
      u'\u00E9pigraphe': 'epigraph',
      u'chapeau': 'highlights',
      u'accroche': 'pull-quote',
      u'compound (translation required)': 'compound',
      #u'questions': 'questions',
      #u'qr': 'questions',
      #u'faq': 'questions',
      u'tableau': 'table',
      u'csv-table (translation required)': 'csv-table',
      u'list-table (translation required)': 'list-table',
      u'm\u00E9ta': 'meta',
      #u'imagemap (translation required)': 'imagemap',
      u'image': 'image',
      u'figure': 'figure',
      u'inclure': 'include',
      u'brut': 'raw',
      u'remplacer': 'replace',
      u'remplace': 'replace',
      u'unicode': 'unicode',
      u'classe': 'class',
      u'role (translation required)': 'role',
      u'sommaire': 'contents',
      u'table-des-mati\u00E8res': 'contents',
      u'sectnum': 'sectnum',
      u'section-num\u00E9rot\u00E9e': 'sectnum',
      u'liens': 'target-notes',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #u'footnotes (translation required)': 'footnotes',
      #u'citations (translation required)': 'citations',
      }
"""French name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
      u'abr\u00E9viation': 'abbreviation',
      u'acronyme': 'acronym',
      u'sigle': 'acronym',
      u'index': 'index',
      u'indice': 'subscript',
      u'ind': 'subscript',
      u'exposant': 'superscript',
      u'exp': 'superscript',
      u'titre-r\u00E9f\u00E9rence': 'title-reference',
      u'titre': 'title-reference',
      u'pep-r\u00E9f\u00E9rence': 'pep-reference',
      u'rfc-r\u00E9f\u00E9rence': 'rfc-reference',
      u'emphase': 'emphasis',
      u'fort': 'strong',
      u'litt\u00E9ral': 'literal',
      u'nomm\u00E9e-r\u00E9f\u00E9rence': 'named-reference',
      u'anonyme-r\u00E9f\u00E9rence': 'anonymous-reference',
      u'note-r\u00E9f\u00E9rence': 'footnote-reference',
      u'citation-r\u00E9f\u00E9rence': 'citation-reference',
      u'substitution-r\u00E9f\u00E9rence': 'substitution-reference',
      u'lien': 'target',
      u'uri-r\u00E9f\u00E9rence': 'uri-reference',
      u'brut': 'raw',}
"""Mapping of French role names to canonical role names for interpreted text.
"""
�������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/es.py������������������������������0000644�0001750�0001750�00000007540�10322224711�026025� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# -*- coding: iso-8859-1 -*-
# Author: Marcelo Huerta San Martn
# Contact: richieadler@users.sourceforge.net
# Revision: $Revision: 3190 $
# Date: $Date: 2005-04-08 05:06:12 +0200 (Fri, 08 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Spanish-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      u'atenci\u00f3n': 'attention',
      u'atencion': 'attention',
      u'precauci\u00f3n': 'caution',
      u'precaucion': 'caution',
      u'peligro': 'danger',
      u'error': 'error',
      u'sugerencia': 'hint',
      u'importante': 'important',
      u'nota': 'note',
      u'consejo': 'tip',
      u'advertencia': 'warning',
      u'exhortacion': 'admonition',
      u'exhortaci\u00f3n': 'admonition',
      u'nota-al-margen': 'sidebar',
      u'tema': 'topic',
      u'bloque-de-lineas': 'line-block',
      u'bloque-de-l\u00edneas': 'line-block',
      u'literal-evaluado': 'parsed-literal',
      u'firma': 'rubric',
      u'ep\u00edgrafe': 'epigraph',
      u'epigrafe': 'epigraph',
      u'destacado': 'highlights',
      u'cita-destacada': 'pull-quote',
      u'combinacion': 'compound',
      u'combinaci\u00f3n': 'compound',
      #'questions': 'questions',
      #'qa': 'questions',
      #'faq': 'questions',
      u'tabla': 'table',
      u'tabla-vsc': 'csv-table',
      u'tabla-csv': 'csv-table',
      u'tabla-lista': 'list-table',
      u'meta': 'meta',
      #'imagemap': 'imagemap',
      u'imagen': 'image',
      u'figura': 'figure',
      u'incluir': 'include',
      u'sin-analisis': 'raw',
      u'sin-an\u00e1lisis': 'raw',
      u'reemplazar': 'replace',
      u'unicode': 'unicode',
      u'clase': 'class',
      u'rol': 'role',
      u'contenido': 'contents',
      u'numseccion': 'sectnum',
      u'numsecci\u00f3n': 'sectnum',
      u'numeracion-seccion': 'sectnum',
      u'numeraci\u00f3n-secci\u00f3n': 'sectnum',
      u'notas-destino': 'target-notes',
      u'cabecera': 'header',
      u'pie': 'footer',
      #'footnotes': 'footnotes',
      #'citations': 'citations',
      u'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""Spanish name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    u'abreviatura': 'abbreviation',
    u'ab': 'abbreviation',
    u'acronimo': 'acronym',
    u'acronimo': 'acronym',
    u'ac': 'acronym',
    u'indice': 'index',
    u'i': 'index',
    u'subindice': 'subscript',
    u'sub\u00edndice': 'subscript',
    u'superindice': 'superscript',
    u'super\u00edndice': 'superscript',
    u'referencia-titulo': 'title-reference',
    u'titulo': 'title-reference',
    u't': 'title-reference',
    u'referencia-pep': 'pep-reference',
    u'pep': 'pep-reference',
    u'referencia-rfc': 'rfc-reference',
    u'rfc': 'rfc-reference',
    u'enfasis': 'emphasis',
    u'\u00e9nfasis': 'emphasis',
    u'destacado': 'strong',
    u'literal': 'literal',              # "literal" is also a word in Spanish :-)
    u'referencia-con-nombre': 'named-reference',
    u'referencia-anonima': 'anonymous-reference',
    u'referencia-an\u00f3nima': 'anonymous-reference',
    u'referencia-nota-al-pie': 'footnote-reference',
    u'referencia-cita': 'citation-reference',
    u'referencia-sustitucion': 'substitution-reference',
    u'referencia-sustituci\u00f3n': 'substitution-reference',
    u'destino': 'target',
    u'referencia-uri': 'uri-reference',
    u'uri': 'uri-reference',
    u'url': 'uri-reference',
    u'sin-analisis': 'raw',
    u'sin-an\u00e1lisis': 'raw',
}
"""Mapping of Spanish role names to canonical role names for interpreted text.
"""
����������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/nl.py������������������������������0000644�0001750�0001750�00000006505�10322225023�026024� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Martijn Pieters
# Contact: mjpieters@users.sourceforge.net
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Dutch-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      'attentie': 'attention',
      'let-op': 'caution',
      'gevaar': 'danger',
      'fout': 'error',
      'hint': 'hint',
      'belangrijk': 'important',
      'opmerking': 'note',
      'tip': 'tip',
      'waarschuwing': 'warning',
      'aanmaning': 'admonition',
      'katern': 'sidebar',
      'onderwerp': 'topic',
      'lijn-blok': 'line-block',
      'letterlijk-ontleed': 'parsed-literal',
      'rubriek': 'rubric',
      'opschrift': 'epigraph',
      'hoogtepunten': 'highlights',
      'pull-quote': 'pull-quote', # Dutch printers use the english term
      'samenstelling': 'compound',
      'verbinding': 'compound',
      #'vragen': 'questions',
      'tabel': 'table',
      'csv-tabel': 'csv-table',
      'lijst-tabel': 'list-table',
      #'veelgestelde-vragen': 'questions',
      'meta': 'meta',
      #'imagemap': 'imagemap',
      'beeld': 'image',
      'figuur': 'figure',
      'opnemen': 'include',
      'onbewerkt': 'raw',
      'vervang': 'replace',
      'vervanging': 'replace',
      'unicode': 'unicode',
      'klasse': 'class',
      'rol': 'role',
      'inhoud': 'contents',
      'sectnum': 'sectnum',
      'sectie-nummering': 'sectnum',
      'hoofdstuk-nummering': 'sectnum',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #'voetnoten': 'footnotes',
      #'citaten': 'citations',
      'verwijzing-voetnoten': 'target-notes',
      'restructuredtext-test-instructie': 'restructuredtext-test-directive'}
"""Dutch name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    # language-dependent: fixed
    'afkorting': 'abbreviation',
    # 'ab': 'abbreviation',
    'acroniem': 'acronym',
    'ac': 'acronym',
    'index': 'index',
    'i': 'index',
    'inferieur': 'subscript',
    'inf': 'subscript',
    'superieur': 'superscript',
    'sup': 'superscript',
    'titel-referentie': 'title-reference',
    'titel': 'title-reference',
    't': 'title-reference',
    'pep-referentie': 'pep-reference',
    'pep': 'pep-reference',
    'rfc-referentie': 'rfc-reference',
    'rfc': 'rfc-reference',
    'nadruk': 'emphasis',
    'extra': 'strong',
    'extra-nadruk': 'strong',
    'vet': 'strong',
    'letterlijk': 'literal',
    'benoemde-referentie': 'named-reference',
    'anonieme-referentie': 'anonymous-reference',
    'voetnoot-referentie': 'footnote-reference',
    'citaat-referentie': 'citation-reference',
    'substitie-reference': 'substitution-reference',
    'verwijzing': 'target',
    'uri-referentie': 'uri-reference',
    'uri': 'uri-reference',
    'url': 'uri-reference',
    'onbewerkt': 'raw',}
"""Mapping of Dutch role names to canonical role names for interpreted text.
"""
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/it.py������������������������������0000644�0001750�0001750�00000005716�10322224711�026035� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Nicola Larosa, Lele Gaifax
# Contact: docutils@tekNico.net, lele@seldati.it
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# Beware: the italian translation of the reStructuredText documentation
# at http://docit.bice.dyndns.org/static/ReST, in particular
# http://docit.bice.dyndns.org/static/ReST/ref/rst/directives.html, needs
# to be synced with the content of this file.

"""
Italian-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      'attenzione': 'attention',
      'cautela': 'caution',
      'pericolo': 'danger',
      'errore': 'error',
      'suggerimento': 'hint',
      'importante': 'important',
      'nota': 'note',
      'consiglio': 'tip',
      'avvertenza': 'warning',
      'ammonizione': 'admonition',
      'riquadro': 'sidebar',
      'argomento': 'topic',
      'blocco-di-righe': 'line-block',
      'blocco-interpretato': 'parsed-literal',
      'rubrica': 'rubric',
      'epigrafe': 'epigraph',
      'punti-salienti': 'highlights',
      'estratto-evidenziato': 'pull-quote',
      'composito': 'compound',
      #'questions': 'questions',
      #'qa': 'questions',
      #'faq': 'questions',
      'tabella': 'table',
      'tabella-csv': 'csv-table',
      'tabella-elenco': 'list-table',
      'meta': 'meta',
      #'imagemap': 'imagemap',
      'immagine': 'image',
      'figura': 'figure',
      'includi': 'include',
      'grezzo': 'raw',
      'sostituisci': 'replace',
      'unicode': 'unicode',
      'classe': 'class',
      'ruolo': 'role',
      'indice': 'contents',
      'contenuti': 'contents',
      'seznum': 'sectnum',
      'sezioni-autonumerate': 'sectnum',
      'annota-riferimenti-esterni': 'target-notes',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #'footnotes': 'footnotes',
      #'citations': 'citations',
      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""Italian name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
      'abbreviazione': 'abbreviation',
      'acronimo': 'acronym',
      'indice': 'index',
      'deponente': 'subscript',
      'esponente': 'superscript',
      'riferimento-titolo': 'title-reference',
      'riferimento-pep': 'pep-reference',
      'riferimento-rfc': 'rfc-reference',
      'enfasi': 'emphasis',
      'forte': 'strong',
      'letterale': 'literal',
      'riferimento-con-nome': 'named-reference',
      'riferimento-anonimo': 'anonymous-reference',
      'riferimento-nota': 'footnote-reference',
      'riferimento-citazione': 'citation-reference',
      'riferimento-sostituzione': 'substitution-reference',
      'destinazione': 'target',
      'riferimento-uri': 'uri-reference',
      'grezzo': 'raw',}
"""Mapping of Italian role names to canonical role names for interpreted text.
"""
��������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/sk.py������������������������������0000644�0001750�0001750�00000007112�10322224711�026026� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Miroslav Vasko
# Contact: zemiak@zoznam.sk
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Slovak-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      u'pozor': 'attention',
      u'opatrne': 'caution',
      u'nebezpe\xe8enstvo': 'danger',
      u'chyba': 'error',
      u'rada': 'hint',
      u'd\xf4le\x9eit\xe9': 'important',
      u'pozn\xe1mka': 'note',
      u'tip (translation required)': 'tip',
      u'varovanie': 'warning',
      u'admonition (translation required)': 'admonition',
      u'sidebar (translation required)': 'sidebar',
      u't\xe9ma': 'topic',
      u'blok-riadkov': 'line-block',
      u'parsed-literal': 'parsed-literal',
      u'rubric (translation required)': 'rubric',
      u'epigraph (translation required)': 'epigraph',
      u'highlights (translation required)': 'highlights',
      u'pull-quote (translation required)': 'pull-quote',
      u'compound (translation required)': 'compound',
      #u'questions': 'questions',
      #u'qa': 'questions',
      #u'faq': 'questions',
      u'table (translation required)': 'table',
      u'csv-table (translation required)': 'csv-table',
      u'list-table (translation required)': 'list-table',
      u'meta': 'meta',
      #u'imagemap': 'imagemap',
      u'obr\xe1zok': 'image',
      u'tvar': 'figure',
      u'vlo\x9ei\x9d': 'include',
      u'raw (translation required)': 'raw',
      u'nahradi\x9d': 'replace',
      u'unicode': 'unicode',
      u'class (translation required)': 'class',
      u'role (translation required)': 'role',
      u'obsah': 'contents',
      u'\xe8as\x9d': 'sectnum',
      u'\xe8as\x9d-\xe8\xedslovanie': 'sectnum',
      u'cie\xbeov\xe9-pozn\xe1mky': 'target-notes',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #u'footnotes': 'footnotes',
      #u'citations': 'citations',
      }
"""Slovak name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
      u'abbreviation (translation required)': 'abbreviation',
      u'acronym (translation required)': 'acronym',
      u'index (translation required)': 'index',
      u'subscript (translation required)': 'subscript',
      u'superscript (translation required)': 'superscript',
      u'title-reference (translation required)': 'title-reference',
      u'pep-reference (translation required)': 'pep-reference',
      u'rfc-reference (translation required)': 'rfc-reference',
      u'emphasis (translation required)': 'emphasis',
      u'strong (translation required)': 'strong',
      u'literal (translation required)': 'literal',
      u'named-reference (translation required)': 'named-reference',
      u'anonymous-reference (translation required)': 'anonymous-reference',
      u'footnote-reference (translation required)': 'footnote-reference',
      u'citation-reference (translation required)': 'citation-reference',
      u'substitution-reference (translation required)': 'substitution-reference',
      u'target (translation required)': 'target',
      u'uri-reference (translation required)': 'uri-reference',
      u'raw (translation required)': 'raw',}
"""Mapping of Slovak role names to canonical role names for interpreted text.
"""
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/ca.py������������������������������0000644�0001750�0001750�00000010070�10322225023�025766� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Ivan Vilata i Balaguer
# Contact: ivan@selidor.net
# Revision: $Revision: 3276 $
# Date: $Date: 2005-04-30 13:34:52 +0200 (Sat, 30 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Catalan-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      # language-dependent: fixed
      u'atenci\u00F3': 'attention',
      u'compte': 'caution',
      u'perill': 'danger',
      u'error': 'error',
      u'suggeriment': 'hint',
      u'important': 'important',
      u'nota': 'note',
      u'consell': 'tip',
      u'av\u00EDs': 'warning',
      u'advertiment': 'admonition',
      u'nota-al-marge': 'sidebar',
      u'nota-marge': 'sidebar',
      u'tema': 'topic',
      u'bloc-de-l\u00EDnies': 'line-block',
      u'bloc-l\u00EDnies': 'line-block',
      u'literal-analitzat': 'parsed-literal',
      u'r\u00FAbrica': 'rubric',
      u'ep\u00EDgraf': 'epigraph',
      u'sumari': 'highlights',
      u'cita-destacada': 'pull-quote',
      u'compost': 'compound',
      #'questions': 'questions',
      u'taula': 'table',
      u'taula-csv': 'csv-table',
      u'taula-llista': 'list-table',
      #'qa': 'questions',
      #'faq': 'questions',
      u'meta': 'meta',
      #'imagemap': 'imagemap',
      u'imatge': 'image',
      u'figura': 'figure',
      u'inclou': 'include',
      u'incloure': 'include',
      u'cru': 'raw',
      u'reempla\u00E7a': 'replace',
      u'reempla\u00E7ar': 'replace',
      u'unicode': 'unicode',
      u'classe': 'class',
      u'rol': 'role',
      u'contingut': 'contents',
      u'numsec': 'sectnum',
      u'numeraci\u00F3-de-seccions': 'sectnum',
      u'numeraci\u00F3-seccions': 'sectnum',
      u'cap\u00E7alera': 'header',
      u'peu-de-p\u00E0gina': 'footer',
      u'peu-p\u00E0gina': 'footer',
      #'footnotes': 'footnotes',
      #'citations': 'citations',
      u'notes-amb-destinacions': 'target-notes',
      u'notes-destinacions': 'target-notes',
      u'directiva-de-prova-de-restructuredtext': 'restructuredtext-test-directive'}
"""Catalan name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    # language-dependent: fixed
    u'abreviatura': 'abbreviation',
    u'abreviaci\u00F3': 'abbreviation',
    u'abrev': 'abbreviation',
    u'ab': 'abbreviation',
    u'acr\u00F2nim': 'acronym',
    u'ac': 'acronym',
    u'\u00EDndex': 'index',
    u'i': 'index',
    u'sub\u00EDndex': 'subscript',
    u'sub': 'subscript',
    u'super\u00EDndex': 'superscript',
    u'sup': 'superscript',
    u'refer\u00E8ncia-a-t\u00EDtol': 'title-reference',
    u'refer\u00E8ncia-t\u00EDtol': 'title-reference',
    u't\u00EDtol': 'title-reference',
    u't': 'title-reference',
    u'refer\u00E8ncia-a-pep': 'pep-reference',
    u'refer\u00E8ncia-pep': 'pep-reference',
    u'pep': 'pep-reference',
    u'refer\u00E8ncia-a-rfc': 'rfc-reference',
    u'refer\u00E8ncia-rfc': 'rfc-reference',
    u'rfc': 'rfc-reference',
    u'\u00E8mfasi': 'emphasis',
    u'destacat': 'strong',
    u'literal': 'literal',
    u'refer\u00E8ncia-amb-nom': 'named-reference',
    u'refer\u00E8ncia-nom': 'named-reference',
    u'refer\u00E8ncia-an\u00F2nima': 'anonymous-reference',
    u'refer\u00E8ncia-a-nota-al-peu': 'footnote-reference',
    u'refer\u00E8ncia-nota-al-peu': 'footnote-reference',
    u'refer\u00E8ncia-a-cita': 'citation-reference',
    u'refer\u00E8ncia-cita': 'citation-reference',
    u'refer\u00E8ncia-a-substituci\u00F3': 'substitution-reference',
    u'refer\u00E8ncia-substituci\u00F3': 'substitution-reference',
    u'destinaci\u00F3': 'target',
    u'refer\u00E8ncia-a-uri': 'uri-reference',
    u'refer\u00E8ncia-uri': 'uri-reference',
    u'uri': 'uri-reference',
    u'url': 'uri-reference',
    u'cru': 'raw',}
"""Mapping of Catalan role names to canonical role names for interpreted text.
"""
������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/ru.py������������������������������0000644�0001750�0001750�00000011715�10322224711�026043� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Roman Suzi
# Contact: rnd@onego.ru
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Russian-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'

directives = {
 u'\u0431\u043b\u043e\u043a-\u0441\u0442\u0440\u043e\u043a': u'line-block',
 u'meta': u'meta',
 u'\u043e\u0431\u0440\u0430\u0431\u043e\u0442\u0430\u043d\u043d\u044b\u0439-\u043b\u0438\u0442\u0435\u0440\u0430\u043b':
 u'parsed-literal',
 u'\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u043d\u0430\u044f-\u0446\u0438\u0442\u0430\u0442\u0430':
 u'pull-quote',
 u'compound (translation required)': 'compound',
 u'table (translation required)': 'table',
 u'csv-table (translation required)': 'csv-table',
 u'list-table (translation required)': 'list-table',
 u'\u0441\u044b\u0440\u043e\u0439': u'raw',
 u'\u0437\u0430\u043c\u0435\u043d\u0430': u'replace',
 u'\u0442\u0435\u0441\u0442\u043e\u0432\u0430\u044f-\u0434\u0438\u0440\u0435\u043a\u0442\u0438\u0432\u0430-restructuredtext':
 u'restructuredtext-test-directive',
 u'\u0446\u0435\u043b\u0435\u0432\u044b\u0435-\u0441\u043d\u043e\u0441\u043a\u0438': 
 u'target-notes',
 u'unicode': u'unicode',
 u'\u0431\u043e\u043a\u043e\u0432\u0430\u044f-\u043f\u043e\u043b\u043e\u0441\u0430':
 u'sidebar',
 u'\u0432\u0430\u0436\u043d\u043e': u'important',
 u'\u0432\u043a\u043b\u044e\u0447\u0430\u0442\u044c': u'include',
 u'\u0432\u043d\u0438\u043c\u0430\u043d\u0438\u0435': u'attention',
 u'\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u0438\u0435': u'highlights',
 u'\u0437\u0430\u043c\u0435\u0447\u0430\u043d\u0438\u0435': u'admonition',
 u'\u0438\u0437\u043e\u0431\u0440\u0430\u0436\u0435\u043d\u0438\u0435':
 u'image',
 u'\u043a\u043b\u0430\u0441\u0441': u'class',
 u'role (translation required)': 'role',
 u'\u043d\u043e\u043c\u0435\u0440-\u0440\u0430\u0437\u0434\u0435\u043b\u0430':
 u'sectnum',
 u'\u043d\u0443\u043c\u0435\u0440\u0430\u0446\u0438\u044f-\u0440\u0430\u0437'
 u'\u0434\u0435\u043b\u043e\u0432': u'sectnum',
 u'\u043e\u043f\u0430\u0441\u043d\u043e': u'danger',
 u'\u043e\u0441\u0442\u043e\u0440\u043e\u0436\u043d\u043e': u'caution',
 u'\u043e\u0448\u0438\u0431\u043a\u0430': u'error',
 u'\u043f\u043e\u0434\u0441\u043a\u0430\u0437\u043a\u0430': u'tip',
 u'\u043f\u0440\u0435\u0434\u0443\u043f\u0440\u0435\u0436\u0434\u0435\u043d'
 u'\u0438\u0435': u'warning',
 u'\u043f\u0440\u0438\u043c\u0435\u0447\u0430\u043d\u0438\u0435': u'note',
 u'\u0440\u0438\u0441\u0443\u043d\u043e\u043a': u'figure',
 u'\u0440\u0443\u0431\u0440\u0438\u043a\u0430': u'rubric',
 u'\u0441\u043e\u0432\u0435\u0442': u'hint',
 u'\u0441\u043e\u0434\u0435\u0440\u0436\u0430\u043d\u0438\u0435': u'contents',
 u'\u0442\u0435\u043c\u0430': u'topic',
 u'\u044d\u043f\u0438\u0433\u0440\u0430\u0444': u'epigraph',
 u'header (translation required)': 'header',
 u'footer (translation required)': 'footer',}
"""Russian name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
 u'\u0430\u043a\u0440\u043e\u043d\u0438\u043c': 'acronym',
 u'\u0430\u043d\u043e\u043d\u0438\u043c\u043d\u0430\u044f-\u0441\u0441\u044b\u043b\u043a\u0430':
  'anonymous-reference',
 u'\u0431\u0443\u043a\u0432\u0430\u043b\u044c\u043d\u043e': 'literal',
 u'\u0432\u0435\u0440\u0445\u043d\u0438\u0439-\u0438\u043d\u0434\u0435\u043a\u0441':
  'superscript',
 u'\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u0438\u0435': 'emphasis',
 u'\u0438\u043c\u0435\u043d\u043e\u0432\u0430\u043d\u043d\u0430\u044f-\u0441\u0441\u044b\u043b\u043a\u0430':
  'named-reference',
 u'\u0438\u043d\u0434\u0435\u043a\u0441': 'index',
 u'\u043d\u0438\u0436\u043d\u0438\u0439-\u0438\u043d\u0434\u0435\u043a\u0441':
  'subscript',
 u'\u0441\u0438\u043b\u044c\u043d\u043e\u0435-\u0432\u044b\u0434\u0435\u043b\u0435\u043d\u0438\u0435':
  'strong',
 u'\u0441\u043e\u043a\u0440\u0430\u0449\u0435\u043d\u0438\u0435':
  'abbreviation',
 u'\u0441\u0441\u044b\u043b\u043a\u0430-\u0437\u0430\u043c\u0435\u043d\u0430':
  'substitution-reference',
 u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-pep': 'pep-reference',
 u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-rfc': 'rfc-reference',
 u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-uri': 'uri-reference',
 u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-\u0437\u0430\u0433\u043b\u0430\u0432\u0438\u0435':
  'title-reference',
 u'\u0441\u0441\u044b\u043b\u043a\u0430-\u043d\u0430-\u0441\u043d\u043e\u0441\u043a\u0443':
  'footnote-reference',
 u'\u0446\u0438\u0442\u0430\u0442\u043d\u0430\u044f-\u0441\u0441\u044b\u043b\u043a\u0430':
  'citation-reference',
 u'\u0446\u0435\u043b\u044c': 'target',
 u'raw (translation required)': 'raw',}
"""Mapping of Russian role names to canonical role names for interpreted text.
"""
���������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/languages/af.py������������������������������0000644�0001750�0001750�00000006447�10322224711�026011� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Jannie Hofmeyr
# Contact: jhsh@sun.ac.za
# Revision: $Revision: 3184 $
# Date: $Date: 2005-04-07 21:36:11 +0200 (Thu, 07 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read <http://docutils.sf.net/docs/howto/i18n.html>.  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Afrikaans-language mappings for language-dependent features of
reStructuredText.
"""

__docformat__ = 'reStructuredText'


directives = {
      'aandag': 'attention',
      'versigtig': 'caution',
      'gevaar': 'danger',
      'fout': 'error',
      'wenk': 'hint',
      'belangrik': 'important',
      'nota': 'note',
      'tip': 'tip', # hint and tip both have the same translation: wenk
      'waarskuwing': 'warning',
      'vermaning': 'admonition',
      'kantstreep': 'sidebar',
      'onderwerp': 'topic',
      'lynblok': 'line-block',
      'parsed-literal (translation required)': 'parsed-literal',
      'rubriek': 'rubric',
      'epigraaf': 'epigraph',
      'hoogtepunte': 'highlights',
      'pull-quote (translation required)': 'pull-quote',
      u'compound (translation required)': 'compound',
      #'vrae': 'questions',
      #'qa': 'questions',
      #'faq': 'questions',
      'table (translation required)': 'table',
      'csv-table (translation required)': 'csv-table',
      'list-table (translation required)': 'list-table',
      'meta': 'meta',
      #'beeldkaart': 'imagemap',
      'beeld': 'image',
      'figuur': 'figure',
      'insluiting': 'include',
      'rou': 'raw',
      'vervang': 'replace',
      'unicode': 'unicode', # should this be translated? unikode
      'klas': 'class',
      'role (translation required)': 'role',
      'inhoud': 'contents',
      'sectnum': 'sectnum',
      'section-numbering': 'sectnum',
      u'header (translation required)': 'header',
      u'footer (translation required)': 'footer',
      #'voetnote': 'footnotes',
      #'aanhalings': 'citations',
      'teikennotas': 'target-notes',
      'restructuredtext-test-directive': 'restructuredtext-test-directive'}
"""Afrikaans name to registered (in directives/__init__.py) directive name
mapping."""

roles = {
    'afkorting': 'abbreviation',
    'ab': 'abbreviation',
    'akroniem': 'acronym',
    'ac': 'acronym',
    'indeks': 'index',
    'i': 'index',
    'voetskrif': 'subscript',
    'sub': 'subscript',
    'boskrif': 'superscript',
    'sup': 'superscript',
    'titelverwysing': 'title-reference',
    'titel': 'title-reference',
    't': 'title-reference',
    'pep-verwysing': 'pep-reference',
    'pep': 'pep-reference',
    'rfc-verwysing': 'rfc-reference',
    'rfc': 'rfc-reference',
    'nadruk': 'emphasis',
    'sterk': 'strong',
    'literal (translation required)': 'literal',
    'benoemde verwysing': 'named-reference',
    'anonieme verwysing': 'anonymous-reference',
    'voetnootverwysing': 'footnote-reference',
    'aanhalingverwysing': 'citation-reference',
    'vervangingsverwysing': 'substitution-reference',
    'teiken': 'target',
    'uri-verwysing': 'uri-reference',
    'uri': 'uri-reference',
    'url': 'uri-reference',
    'rou': 'raw',}
"""Mapping of Afrikaans role names to canonical role names for interpreted text.
"""
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/tableparser.py�������������������������������0000644�0001750�0001750�00000047300�10322224711�025752� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 1574 $
# Date: $Date: 2003-07-06 00:38:28 +0200 (Sun, 06 Jul 2003) $
# Copyright: This module has been placed in the public domain.

"""
This module defines table parser classes,which parse plaintext-graphic tables
and produce a well-formed data structure suitable for building a CALS table.

:Classes:
    - `GridTableParser`: Parse fully-formed tables represented with a grid.
    - `SimpleTableParser`: Parse simple tables, delimited by top & bottom
      borders.

:Exception class: `TableMarkupError`

:Function:
    `update_dict_of_lists()`: Merge two dictionaries containing list values.
"""

__docformat__ = 'reStructuredText'


import re
import sys
from docutils import DataError


class TableMarkupError(DataError): pass


class TableParser:

    """
    Abstract superclass for the common parts of the syntax-specific parsers.
    """

    head_body_separator_pat = None
    """Matches the row separator between head rows and body rows."""

    def parse(self, block):
        """
        Analyze the text `block` and return a table data structure.

        Given a plaintext-graphic table in `block` (list of lines of text; no
        whitespace padding), parse the table, construct and return the data
        necessary to construct a CALS table or equivalent.

        Raise `TableMarkupError` if there is any problem with the markup.
        """
        self.setup(block)
        self.find_head_body_sep()
        self.parse_table()
        structure = self.structure_from_cells()
        return structure

    def find_head_body_sep(self):
        """Look for a head/body row separator line; store the line index."""
        for i in range(len(self.block)):
            line = self.block[i]
            if self.head_body_separator_pat.match(line):
                if self.head_body_sep:
                    raise TableMarkupError(
                        'Multiple head/body row separators in table (at line '
                        'offset %s and %s); only one allowed.'
                        % (self.head_body_sep, i))
                else:
                    self.head_body_sep = i
                    self.block[i] = line.replace('=', '-')
        if self.head_body_sep == 0 or self.head_body_sep == (len(self.block)
                                                             - 1):
            raise TableMarkupError('The head/body row separator may not be '
                                   'the first or last line of the table.')


class GridTableParser(TableParser):

    """
    Parse a grid table using `parse()`.

    Here's an example of a grid table::

        +------------------------+------------+----------+----------+
        | Header row, column 1   | Header 2   | Header 3 | Header 4 |
        +========================+============+==========+==========+
        | body row 1, column 1   | column 2   | column 3 | column 4 |
        +------------------------+------------+----------+----------+
        | body row 2             | Cells may span columns.          |
        +------------------------+------------+---------------------+
        | body row 3             | Cells may  | - Table cells       |
        +------------------------+ span rows. | - contain           |
        | body row 4             |            | - body elements.    |
        +------------------------+------------+---------------------+

    Intersections use '+', row separators use '-' (except for one optional
    head/body row separator, which uses '='), and column separators use '|'.

    Passing the above table to the `parse()` method will result in the
    following data structure::

        ([24, 12, 10, 10],
         [[(0, 0, 1, ['Header row, column 1']),
           (0, 0, 1, ['Header 2']),
           (0, 0, 1, ['Header 3']),
           (0, 0, 1, ['Header 4'])]],
         [[(0, 0, 3, ['body row 1, column 1']),
           (0, 0, 3, ['column 2']),
           (0, 0, 3, ['column 3']),
           (0, 0, 3, ['column 4'])],
          [(0, 0, 5, ['body row 2']),
           (0, 2, 5, ['Cells may span columns.']),
           None,
           None],
          [(0, 0, 7, ['body row 3']),
           (1, 0, 7, ['Cells may', 'span rows.', '']),
           (1, 1, 7, ['- Table cells', '- contain', '- body elements.']),
           None],
          [(0, 0, 9, ['body row 4']), None, None, None]])

    The first item is a list containing column widths (colspecs). The second
    item is a list of head rows, and the third is a list of body rows. Each
    row contains a list of cells. Each cell is either None (for a cell unused
    because of another cell's span), or a tuple. A cell tuple contains four
    items: the number of extra rows used by the cell in a vertical span
    (morerows); the number of extra columns used by the cell in a horizontal
    span (morecols); the line offset of the first line of the cell contents;
    and the cell contents, a list of lines of text.
    """

    head_body_separator_pat = re.compile(r'\+=[=+]+=\+ *$')

    def setup(self, block):
        self.block = block[:]           # make a copy; it may be modified
        self.block.disconnect()         # don't propagate changes to parent
        self.bottom = len(block) - 1
        self.right = len(block[0]) - 1
        self.head_body_sep = None
        self.done = [-1] * len(block[0])
        self.cells = []
        self.rowseps = {0: [0]}
        self.colseps = {0: [0]}

    def parse_table(self):
        """
        Start with a queue of upper-left corners, containing the upper-left
        corner of the table itself. Trace out one rectangular cell, remember
        it, and add its upper-right and lower-left corners to the queue of
        potential upper-left corners of further cells. Process the queue in
        top-to-bottom order, keeping track of how much of each text column has
        been seen.

        We'll end up knowing all the row and column boundaries, cell positions
        and their dimensions.
        """
        corners = [(0, 0)]
        while corners:
            top, left = corners.pop(0)
            if top == self.bottom or left == self.right \
                  or top <= self.done[left]:
                continue
            result = self.scan_cell(top, left)
            if not result:
                continue
            bottom, right, rowseps, colseps = result
            update_dict_of_lists(self.rowseps, rowseps)
            update_dict_of_lists(self.colseps, colseps)
            self.mark_done(top, left, bottom, right)
            cellblock = self.block.get_2D_block(top + 1, left + 1,
                                                bottom, right)
            cellblock.disconnect()      # lines in cell can't sync with parent
            self.cells.append((top, left, bottom, right, cellblock))
            corners.extend([(top, right), (bottom, left)])
            corners.sort()
        if not self.check_parse_complete():
            raise TableMarkupError('Malformed table; parse incomplete.')

    def mark_done(self, top, left, bottom, right):
        """For keeping track of how much of each text column has been seen."""
        before = top - 1
        after = bottom - 1
        for col in range(left, right):
            assert self.done[col] == before
            self.done[col] = after

    def check_parse_complete(self):
        """Each text column should have been completely seen."""
        last = self.bottom - 1
        for col in range(self.right):
            if self.done[col] != last:
                return None
        return 1

    def scan_cell(self, top, left):
        """Starting at the top-left corner, start tracing out a cell."""
        assert self.block[top][left] == '+'
        result = self.scan_right(top, left)
        return result

    def scan_right(self, top, left):
        """
        Look for the top-right corner of the cell, and make note of all column
        boundaries ('+').
        """
        colseps = {}
        line = self.block[top]
        for i in range(left + 1, self.right + 1):
            if line[i] == '+':
                colseps[i] = [top]
                result = self.scan_down(top, left, i)
                if result:
                    bottom, rowseps, newcolseps = result
                    update_dict_of_lists(colseps, newcolseps)
                    return bottom, i, rowseps, colseps
            elif line[i] != '-':
                return None
        return None

    def scan_down(self, top, left, right):
        """
        Look for the bottom-right corner of the cell, making note of all row
        boundaries.
        """
        rowseps = {}
        for i in range(top + 1, self.bottom + 1):
            if self.block[i][right] == '+':
                rowseps[i] = [right]
                result = self.scan_left(top, left, i, right)
                if result:
                    newrowseps, colseps = result
                    update_dict_of_lists(rowseps, newrowseps)
                    return i, rowseps, colseps
            elif self.block[i][right] != '|':
                return None
        return None

    def scan_left(self, top, left, bottom, right):
        """
        Noting column boundaries, look for the bottom-left corner of the cell.
        It must line up with the starting point.
        """
        colseps = {}
        line = self.block[bottom]
        for i in range(right - 1, left, -1):
            if line[i] == '+':
                colseps[i] = [bottom]
            elif line[i] != '-':
                return None
        if line[left] != '+':
            return None
        result = self.scan_up(top, left, bottom, right)
        if result is not None:
            rowseps = result
            return rowseps, colseps
        return None

    def scan_up(self, top, left, bottom, right):
        """
        Noting row boundaries, see if we can return to the starting point.
        """
        rowseps = {}
        for i in range(bottom - 1, top, -1):
            if self.block[i][left] == '+':
                rowseps[i] = [left]
            elif self.block[i][left] != '|':
                return None
        return rowseps

    def structure_from_cells(self):
        """
        From the data collected by `scan_cell()`, convert to the final data
        structure.
        """
        rowseps = self.rowseps.keys()   # list of row boundaries
        rowseps.sort()
        rowindex = {}
        for i in range(len(rowseps)):
            rowindex[rowseps[i]] = i    # row boundary -> row number mapping
        colseps = self.colseps.keys()   # list of column boundaries
        colseps.sort()
        colindex = {}
        for i in range(len(colseps)):
            colindex[colseps[i]] = i    # column boundary -> col number map
        colspecs = [(colseps[i] - colseps[i - 1] - 1)
                    for i in range(1, len(colseps))] # list of column widths
        # prepare an empty table with the correct number of rows & columns
        onerow = [None for i in range(len(colseps) - 1)]
        rows = [onerow[:] for i in range(len(rowseps) - 1)]
        # keep track of # of cells remaining; should reduce to zero
        remaining = (len(rowseps) - 1) * (len(colseps) - 1)
        for top, left, bottom, right, block in self.cells:
            rownum = rowindex[top]
            colnum = colindex[left]
            assert rows[rownum][colnum] is None, (
                  'Cell (row %s, column %s) already used.'
                  % (rownum + 1, colnum + 1))
            morerows = rowindex[bottom] - rownum - 1
            morecols = colindex[right] - colnum - 1
            remaining -= (morerows + 1) * (morecols + 1)
            # write the cell into the table
            rows[rownum][colnum] = (morerows, morecols, top + 1, block)
        assert remaining == 0, 'Unused cells remaining.'
        if self.head_body_sep:          # separate head rows from body rows
            numheadrows = rowindex[self.head_body_sep]
            headrows = rows[:numheadrows]
            bodyrows = rows[numheadrows:]
        else:
            headrows = []
            bodyrows = rows
        return (colspecs, headrows, bodyrows)


class SimpleTableParser(TableParser):

    """
    Parse a simple table using `parse()`.

    Here's an example of a simple table::

        =====  =====
        col 1  col 2
        =====  =====
        1      Second column of row 1.
        2      Second column of row 2.
               Second line of paragraph.
        3      - Second column of row 3.

               - Second item in bullet
                 list (row 3, column 2).
        4 is a span
        ------------
        5
        =====  =====

    Top and bottom borders use '=', column span underlines use '-', column
    separation is indicated with spaces.

    Passing the above table to the `parse()` method will result in the
    following data structure, whose interpretation is the same as for
    `GridTableParser`::

        ([5, 25],
         [[(0, 0, 1, ['col 1']),
           (0, 0, 1, ['col 2'])]],
         [[(0, 0, 3, ['1']),
           (0, 0, 3, ['Second column of row 1.'])],
          [(0, 0, 4, ['2']),
           (0, 0, 4, ['Second column of row 2.',
                      'Second line of paragraph.'])],
          [(0, 0, 6, ['3']),
           (0, 0, 6, ['- Second column of row 3.',
                      '',
                      '- Second item in bullet',
                      '  list (row 3, column 2).'])],
          [(0, 1, 10, ['4 is a span'])],
          [(0, 0, 12, ['5']),
           (0, 0, 12, [''])]])
    """

    head_body_separator_pat = re.compile('=[ =]*$')
    span_pat = re.compile('-[ -]*$')

    def setup(self, block):
        self.block = block[:]           # make a copy; it will be modified
        self.block.disconnect()         # don't propagate changes to parent
        # Convert top & bottom borders to column span underlines:
        self.block[0] = self.block[0].replace('=', '-')
        self.block[-1] = self.block[-1].replace('=', '-')
        self.head_body_sep = None
        self.columns = []
        self.border_end = None
        self.table = []
        self.done = [-1] * len(block[0])
        self.rowseps = {0: [0]}
        self.colseps = {0: [0]}

    def parse_table(self):
        """
        First determine the column boundaries from the top border, then
        process rows.  Each row may consist of multiple lines; accumulate
        lines until a row is complete.  Call `self.parse_row` to finish the
        job.
        """
        # Top border must fully describe all table columns.
        self.columns = self.parse_columns(self.block[0], 0)
        self.border_end = self.columns[-1][1]
        firststart, firstend = self.columns[0]
        offset = 1                      # skip top border
        start = 1
        text_found = None
        while offset < len(self.block):
            line = self.block[offset]
            if self.span_pat.match(line):
                # Column span underline or border; row is complete.
                self.parse_row(self.block[start:offset], start,
                               (line.rstrip(), offset))
                start = offset + 1
                text_found = None
            elif line[firststart:firstend].strip():
                # First column not blank, therefore it's a new row.
                if text_found and offset != start:
                    self.parse_row(self.block[start:offset], start)
                start = offset
                text_found = 1
            elif not text_found:
                start = offset + 1
            offset += 1

    def parse_columns(self, line, offset):
        """
        Given a column span underline, return a list of (begin, end) pairs.
        """
        cols = []
        end = 0
        while 1:
            begin = line.find('-', end)
            end = line.find(' ', begin)
            if begin < 0:
                break
            if end < 0:
                end = len(line)
            cols.append((begin, end))
        if self.columns:
            if cols[-1][1] != self.border_end:
                raise TableMarkupError('Column span incomplete at line '
                                       'offset %s.' % offset)
            # Allow for an unbounded rightmost column:
            cols[-1] = (cols[-1][0], self.columns[-1][1])
        return cols

    def init_row(self, colspec, offset):
        i = 0
        cells = []
        for start, end in colspec:
            morecols = 0
            try:
                assert start == self.columns[i][0]
                while end != self.columns[i][1]:
                    i += 1
                    morecols += 1
            except (AssertionError, IndexError):
                raise TableMarkupError('Column span alignment problem at '
                                       'line offset %s.' % (offset + 1))
            cells.append([0, morecols, offset, []])
            i += 1
        return cells

    def parse_row(self, lines, start, spanline=None):
        """
        Given the text `lines` of a row, parse it and append to `self.table`.

        The row is parsed according to the current column spec (either
        `spanline` if provided or `self.columns`).  For each column, extract
        text from each line, and check for text in column margins.  Finally,
        adjust for insigificant whitespace.
        """
        if not (lines or spanline):
            # No new row, just blank lines.
            return
        if spanline:
            columns = self.parse_columns(*spanline)
            span_offset = spanline[1]
        else:
            columns = self.columns[:]
            span_offset = start
        self.check_columns(lines, start, columns)
        row = self.init_row(columns, start)
        for i in range(len(columns)):
            start, end = columns[i]
            cellblock = lines.get_2D_block(0, start, len(lines), end)
            cellblock.disconnect()      # lines in cell can't sync with parent
            row[i][3] = cellblock
        self.table.append(row)

    def check_columns(self, lines, first_line, columns):
        """
        Check for text in column margins and text overflow in the last column.
        Raise TableMarkupError if anything but whitespace is in column margins.
        Adjust the end value for the last column if there is text overflow.
        """
        # "Infinite" value for a dummy last column's beginning, used to
        # check for text overflow:
        columns.append((sys.maxint, None))
        lastcol = len(columns) - 2
        for i in range(len(columns) - 1):
            start, end = columns[i]
            nextstart = columns[i+1][0]
            offset = 0
            for line in lines:
                if i == lastcol and line[end:].strip():
                    text = line[start:].rstrip()
                    new_end = start + len(text)
                    columns[i] = (start, new_end)
                    main_start, main_end = self.columns[-1]
                    if new_end > main_end:
                        self.columns[-1] = (main_start, new_end)
                elif line[end:nextstart].strip():
                    raise TableMarkupError('Text in column margin at line '
                                           'offset %s.' % (first_line + offset))
                offset += 1
        columns.pop()

    def structure_from_cells(self):
        colspecs = [end - start for start, end in self.columns]
        first_body_row = 0
        if self.head_body_sep:
            for i in range(len(self.table)):
                if self.table[i][0][2] > self.head_body_sep:
                    first_body_row = i
                    break
        return (colspecs, self.table[:first_body_row],
                self.table[first_body_row:])


def update_dict_of_lists(master, newdata):
    """
    Extend the list values of `master` with those from `newdata`.

    Both parameters must be dictionaries containing list values.
    """
    for key, values in newdata.items():
        master.setdefault(key, []).extend(values)
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/states.py������������������������������������0000644�0001750�0001750�00000357775�10322224711�024775� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3253 $
# Date: $Date: 2005-04-25 17:08:01 +0200 (Mon, 25 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
This is the ``docutils.parsers.restructuredtext.states`` module, the core of
the reStructuredText parser.  It defines the following:

:Classes:
    - `RSTStateMachine`: reStructuredText parser's entry point.
    - `NestedStateMachine`: recursive StateMachine.
    - `RSTState`: reStructuredText State superclass.
    - `Inliner`: For parsing inline markup.
    - `Body`: Generic classifier of the first line of a block.
    - `SpecializedBody`: Superclass for compound element members.
    - `BulletList`: Second and subsequent bullet_list list_items
    - `DefinitionList`: Second+ definition_list_items.
    - `EnumeratedList`: Second+ enumerated_list list_items.
    - `FieldList`: Second+ fields.
    - `OptionList`: Second+ option_list_items.
    - `RFC2822List`: Second+ RFC2822-style fields.
    - `ExtensionOptions`: Parses directive option fields.
    - `Explicit`: Second+ explicit markup constructs.
    - `SubstitutionDef`: For embedded directives in substitution definitions.
    - `Text`: Classifier of second line of a text block.
    - `SpecializedText`: Superclass for continuation lines of Text-variants.
    - `Definition`: Second line of potential definition_list_item.
    - `Line`: Second line of overlined section title or transition marker.
    - `Struct`: An auxiliary collection class.

:Exception classes:
    - `MarkupError`
    - `ParserError`
    - `MarkupMismatch`

:Functions:
    - `escape2null()`: Return a string, escape-backslashes converted to nulls.
    - `unescape()`: Return a string, nulls removed or restored to backslashes.

:Attributes:
    - `state_classes`: set of State classes used with `RSTStateMachine`.

Parser Overview
===============

The reStructuredText parser is implemented as a recursive state machine,
examining its input one line at a time.  To understand how the parser works,
please first become familiar with the `docutils.statemachine` module.  In the
description below, references are made to classes defined in this module;
please see the individual classes for details.

Parsing proceeds as follows:

1. The state machine examines each line of input, checking each of the
   transition patterns of the state `Body`, in order, looking for a match.
   The implicit transitions (blank lines and indentation) are checked before
   any others.  The 'text' transition is a catch-all (matches anything).

2. The method associated with the matched transition pattern is called.

   A. Some transition methods are self-contained, appending elements to the
      document tree (`Body.doctest` parses a doctest block).  The parser's
      current line index is advanced to the end of the element, and parsing
      continues with step 1.

   B. Other transition methods trigger the creation of a nested state machine,
      whose job is to parse a compound construct ('indent' does a block quote,
      'bullet' does a bullet list, 'overline' does a section [first checking
      for a valid section header], etc.).

      - In the case of lists and explicit markup, a one-off state machine is
        created and run to parse contents of the first item.

      - A new state machine is created and its initial state is set to the
        appropriate specialized state (`BulletList` in the case of the
        'bullet' transition; see `SpecializedBody` for more detail).  This
        state machine is run to parse the compound element (or series of
        explicit markup elements), and returns as soon as a non-member element
        is encountered.  For example, the `BulletList` state machine ends as
        soon as it encounters an element which is not a list item of that
        bullet list.  The optional omission of inter-element blank lines is
        enabled by this nested state machine.

      - The current line index is advanced to the end of the elements parsed,
        and parsing continues with step 1.

   C. The result of the 'text' transition depends on the next line of text.
      The current state is changed to `Text`, under which the second line is
      examined.  If the second line is:

      - Indented: The element is a definition list item, and parsing proceeds
        similarly to step 2.B, using the `DefinitionList` state.

      - A line of uniform punctuation characters: The element is a section
        header; again, parsing proceeds as in step 2.B, and `Body` is still
        used.

      - Anything else: The element is a paragraph, which is examined for
        inline markup and appended to the parent element.  Processing
        continues with step 1.
"""

__docformat__ = 'reStructuredText'


import sys
import re
import roman
from types import TupleType
from docutils import nodes, statemachine, utils, urischemes
from docutils import ApplicationError, DataError
from docutils.statemachine import StateMachineWS, StateWS
from docutils.nodes import fully_normalize_name as normalize_name
from docutils.nodes import whitespace_normalize_name
from docutils.utils import escape2null, unescape
from docutils.parsers.rst import directives, languages, tableparser, roles
from docutils.parsers.rst.languages import en as _fallback_language_module


class MarkupError(DataError): pass
class UnknownInterpretedRoleError(DataError): pass
class InterpretedRoleNotImplementedError(DataError): pass
class ParserError(ApplicationError): pass
class MarkupMismatch(Exception): pass


class Struct:

    """Stores data attributes for dotted-attribute access."""

    def __init__(self, **keywordargs):
        self.__dict__.update(keywordargs)


class RSTStateMachine(StateMachineWS):

    """
    reStructuredText's master StateMachine.

    The entry point to reStructuredText parsing is the `run()` method.
    """

    def run(self, input_lines, document, input_offset=0, match_titles=1,
            inliner=None):
        """
        Parse `input_lines` and modify the `document` node in place.

        Extend `StateMachineWS.run()`: set up parse-global data and
        run the StateMachine.
        """
        self.language = languages.get_language(
            document.settings.language_code)
        self.match_titles = match_titles
        if inliner is None:
            inliner = Inliner()
        inliner.init_customizations(document.settings)
        self.memo = Struct(document=document,
                           reporter=document.reporter,
                           language=self.language,
                           title_styles=[],
                           section_level=0,
                           section_bubble_up_kludge=0,
                           inliner=inliner)
        self.document = document
        self.attach_observer(document.note_source)
        self.reporter = self.memo.reporter
        self.node = document
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
        assert results == [], 'RSTStateMachine.run() results should be empty!'
        self.node = self.memo = None    # remove unneeded references


class NestedStateMachine(StateMachineWS):

    """
    StateMachine run from within other StateMachine runs, to parse nested
    document structures.
    """

    def run(self, input_lines, input_offset, memo, node, match_titles=1):
        """
        Parse `input_lines` and populate a `docutils.nodes.document` instance.

        Extend `StateMachineWS.run()`: set up document-wide data.
        """
        self.match_titles = match_titles
        self.memo = memo
        self.document = memo.document
        self.attach_observer(self.document.note_source)
        self.reporter = memo.reporter
        self.language = memo.language
        self.node = node
        results = StateMachineWS.run(self, input_lines, input_offset)
        assert results == [], ('NestedStateMachine.run() results should be '
                               'empty!')
        return results


class RSTState(StateWS):

    """
    reStructuredText State superclass.

    Contains methods used by all State subclasses.
    """

    nested_sm = NestedStateMachine

    def __init__(self, state_machine, debug=0):
        self.nested_sm_kwargs = {'state_classes': state_classes,
                                 'initial_state': 'Body'}
        StateWS.__init__(self, state_machine, debug)

    def runtime_init(self):
        StateWS.runtime_init(self)
        memo = self.state_machine.memo
        self.memo = memo
        self.reporter = memo.reporter
        self.inliner = memo.inliner
        self.document = memo.document
        self.parent = self.state_machine.node

    def goto_line(self, abs_line_offset):
        """
        Jump to input line `abs_line_offset`, ignoring jumps past the end.
        """
        try:
            self.state_machine.goto_line(abs_line_offset)
        except EOFError:
            pass

    def no_match(self, context, transitions):
        """
        Override `StateWS.no_match` to generate a system message.

        This code should never be run.
        """
        self.reporter.severe(
            'Internal error: no transition pattern match.  State: "%s"; '
            'transitions: %s; context: %s; current line: %r.'
            % (self.__class__.__name__, transitions, context,
               self.state_machine.line),
            line=self.state_machine.abs_line_number())
        return context, None, []

    def bof(self, context):
        """Called at beginning of file."""
        return [], []

    def nested_parse(self, block, input_offset, node, match_titles=0,
                     state_machine_class=None, state_machine_kwargs=None):
        """
        Create a new StateMachine rooted at `node` and run it over the input
        `block`.
        """
        if state_machine_class is None:
            state_machine_class = self.nested_sm
        if state_machine_kwargs is None:
            state_machine_kwargs = self.nested_sm_kwargs
        block_length = len(block)
        state_machine = state_machine_class(debug=self.debug,
                                            **state_machine_kwargs)
        state_machine.run(block, input_offset, memo=self.memo,
                          node=node, match_titles=match_titles)
        state_machine.unlink()
        new_offset = state_machine.abs_line_offset()
        # No `block.parent` implies disconnected -- lines aren't in sync:
        if block.parent and (len(block) - block_length) != 0:
            # Adjustment for block if modified in nested parse:
            self.state_machine.next_line(len(block) - block_length)
        return new_offset

    def nested_list_parse(self, block, input_offset, node, initial_state,
                          blank_finish,
                          blank_finish_state=None,
                          extra_settings={},
                          match_titles=0,
                          state_machine_class=None,
                          state_machine_kwargs=None):
        """
        Create a new StateMachine rooted at `node` and run it over the input
        `block`. Also keep track of optional intermediate blank lines and the
        required final one.
        """
        if state_machine_class is None:
            state_machine_class = self.nested_sm
        if state_machine_kwargs is None:
            state_machine_kwargs = self.nested_sm_kwargs.copy()
        state_machine_kwargs['initial_state'] = initial_state
        state_machine = state_machine_class(debug=self.debug,
                                            **state_machine_kwargs)
        if blank_finish_state is None:
            blank_finish_state = initial_state
        state_machine.states[blank_finish_state].blank_finish = blank_finish
        for key, value in extra_settings.items():
            setattr(state_machine.states[initial_state], key, value)
        state_machine.run(block, input_offset, memo=self.memo,
                          node=node, match_titles=match_titles)
        blank_finish = state_machine.states[blank_finish_state].blank_finish
        state_machine.unlink()
        return state_machine.abs_line_offset(), blank_finish

    def section(self, title, source, style, lineno, messages):
        """Check for a valid subsection and create one if it checks out."""
        if self.check_subsection(source, style, lineno):
            self.new_subsection(title, lineno, messages)

    def check_subsection(self, source, style, lineno):
        """
        Check for a valid subsection header.  Return 1 (true) or None (false).

        When a new section is reached that isn't a subsection of the current
        section, back up the line count (use ``previous_line(-x)``), then
        ``raise EOFError``.  The current StateMachine will finish, then the
        calling StateMachine can re-examine the title.  This will work its way
        back up the calling chain until the correct section level isreached.

        @@@ Alternative: Evaluate the title, store the title info & level, and
        back up the chain until that level is reached.  Store in memo? Or
        return in results?

        :Exception: `EOFError` when a sibling or supersection encountered.
        """
        memo = self.memo
        title_styles = memo.title_styles
        mylevel = memo.section_level
        try:                            # check for existing title style
            level = title_styles.index(style) + 1
        except ValueError:              # new title style
            if len(title_styles) == memo.section_level: # new subsection
                title_styles.append(style)
                return 1
            else:                       # not at lowest level
                self.parent += self.title_inconsistent(source, lineno)
                return None
        if level <= mylevel:            # sibling or supersection
            memo.section_level = level   # bubble up to parent section
            if len(style) == 2:
                memo.section_bubble_up_kludge = 1
            # back up 2 lines for underline title, 3 for overline title
            self.state_machine.previous_line(len(style) + 1)
            raise EOFError              # let parent section re-evaluate
        if level == mylevel + 1:        # immediate subsection
            return 1
        else:                           # invalid subsection
            self.parent += self.title_inconsistent(source, lineno)
            return None

    def title_inconsistent(self, sourcetext, lineno):
        error = self.reporter.severe(
            'Title level inconsistent:', nodes.literal_block('', sourcetext),
            line=lineno)
        return error

    def new_subsection(self, title, lineno, messages):
        """Append new subsection to document tree. On return, check level."""
        memo = self.memo
        mylevel = memo.section_level
        memo.section_level += 1
        section_node = nodes.section()
        self.parent += section_node
        textnodes, title_messages = self.inline_text(title, lineno)
        titlenode = nodes.title(title, '', *textnodes)
        name = normalize_name(titlenode.astext())
        section_node['names'].append(name)
        section_node += titlenode
        section_node += messages
        section_node += title_messages
        self.document.note_implicit_target(section_node, section_node)
        offset = self.state_machine.line_offset + 1
        absoffset = self.state_machine.abs_line_offset() + 1
        newabsoffset = self.nested_parse(
              self.state_machine.input_lines[offset:], input_offset=absoffset,
              node=section_node, match_titles=1)
        self.goto_line(newabsoffset)
        if memo.section_level <= mylevel: # can't handle next section?
            raise EOFError              # bubble up to supersection
        # reset section_level; next pass will detect it properly
        memo.section_level = mylevel

    def paragraph(self, lines, lineno):
        """
        Return a list (paragraph & messages) & a boolean: literal_block next?
        """
        data = '\n'.join(lines).rstrip()
        if data[-2:] == '::':
            if len(data) == 2:
                return [], 1
            elif data[-3] in ' \n':
                text = data[:-3].rstrip()
            else:
                text = data[:-1]
            literalnext = 1
        else:
            text = data
            literalnext = 0
        textnodes, messages = self.inline_text(text, lineno)
        p = nodes.paragraph(data, '', *textnodes)
        p.line = lineno
        return [p] + messages, literalnext

    def inline_text(self, text, lineno):
        """
        Return 2 lists: nodes (text and inline elements), and system_messages.
        """
        return self.inliner.parse(text, lineno, self.memo, self.parent)

    def unindent_warning(self, node_name):
        return self.reporter.warning(
            '%s ends without a blank line; unexpected unindent.' % node_name,
            line=(self.state_machine.abs_line_number() + 1))


def build_regexp(definition, compile=1):
    """
    Build, compile and return a regular expression based on `definition`.

    :Parameter: `definition`: a 4-tuple (group name, prefix, suffix, parts),
        where "parts" is a list of regular expressions and/or regular
        expression definitions to be joined into an or-group.
    """
    name, prefix, suffix, parts = definition
    part_strings = []
    for part in parts:
        if type(part) is TupleType:
            part_strings.append(build_regexp(part, None))
        else:
            part_strings.append(part)
    or_group = '|'.join(part_strings)
    regexp = '%(prefix)s(?P<%(name)s>%(or_group)s)%(suffix)s' % locals()
    if compile:
        return re.compile(regexp, re.UNICODE)
    else:
        return regexp


class Inliner:

    """
    Parse inline markup; call the `parse()` method.
    """

    def __init__(self, roles=None):
        """
        `roles` is a mapping of canonical role name to role function or bound
        method, which enables additional interpreted text roles.
        """

        self.implicit_dispatch = [(self.patterns.uri, self.standalone_uri),]
        """List of (pattern, bound method) tuples, used by
        `self.implicit_inline`."""

    def init_customizations(self, settings):
        """Setting-based customizations; run when parsing begins."""
        if settings.pep_references:
            self.implicit_dispatch.append((self.patterns.pep,
                                           self.pep_reference))
        if settings.rfc_references:
            self.implicit_dispatch.append((self.patterns.rfc,
                                           self.rfc_reference))

    def parse(self, text, lineno, memo, parent):
        # Needs to be refactored for nested inline markup.
        # Add nested_parse() method?
        """
        Return 2 lists: nodes (text and inline elements), and system_messages.

        Using `self.patterns.initial`, a pattern which matches start-strings
        (emphasis, strong, interpreted, phrase reference, literal,
        substitution reference, and inline target) and complete constructs
        (simple reference, footnote reference), search for a candidate.  When
        one is found, check for validity (e.g., not a quoted '*' character).
        If valid, search for the corresponding end string if applicable, and
        check it for validity.  If not found or invalid, generate a warning
        and ignore the start-string.  Implicit inline markup (e.g. standalone
        URIs) is found last.
        """
        self.reporter = memo.reporter
        self.document = memo.document
        self.language = memo.language
        self.parent = parent
        pattern_search = self.patterns.initial.search
        dispatch = self.dispatch
        remaining = escape2null(text)
        processed = []
        unprocessed = []
        messages = []
        while remaining:
            match = pattern_search(remaining)
            if match:
                groups = match.groupdict()
                method = dispatch[groups['start'] or groups['backquote']
                                  or groups['refend'] or groups['fnend']]
                before, inlines, remaining, sysmessages = method(self, match,
                                                                 lineno)
                unprocessed.append(before)
                messages += sysmessages
                if inlines:
                    processed += self.implicit_inline(''.join(unprocessed),
                                                      lineno)
                    processed += inlines
                    unprocessed = []
            else:
                break
        remaining = ''.join(unprocessed) + remaining
        if remaining:
            processed += self.implicit_inline(remaining, lineno)
        return processed, messages

    openers = '\'"([{<'
    closers = '\'")]}>'
    start_string_prefix = (r'((?<=^)|(?<=[-/: \n%s]))' % re.escape(openers))
    end_string_suffix = (r'((?=$)|(?=[-/:.,;!? \n\x00%s]))'
                         % re.escape(closers))
    non_whitespace_before = r'(?<![ \n])'
    non_whitespace_escape_before = r'(?<![ \n\x00])'
    non_whitespace_after = r'(?![ \n])'
    # Alphanumerics with isolated internal [-._] chars (i.e. not 2 together):
    simplename = r'(?:(?!_)\w)+(?:[-._](?:(?!_)\w)+)*'
    # Valid URI characters (see RFC 2396 & RFC 2732);
    # final \x00 allows backslash escapes in URIs:
    uric = r"""[-_.!~*'()[\];/:@&=+$,%a-zA-Z0-9\x00]"""
    # Delimiter indicating the end of a URI (not part of the URI):
    uri_end_delim = r"""[>]"""
    # Last URI character; same as uric but no punctuation:
    urilast = r"""[_~*/=+a-zA-Z0-9]"""
    # End of a URI (either 'urilast' or 'uric followed by a
    # uri_end_delim'):
    uri_end = r"""(?:%(urilast)s|%(uric)s(?=%(uri_end_delim)s))""" % locals()
    emailc = r"""[-_!~*'{|}/#?^`&=+$%a-zA-Z0-9\x00]"""
    email_pattern = r"""
          %(emailc)s+(?:\.%(emailc)s+)*   # name
          (?<!\x00)@                      # at
          %(emailc)s+(?:\.%(emailc)s*)*   # host
          %(uri_end)s                     # final URI char
          """
    parts = ('initial_inline', start_string_prefix, '',
             [('start', '', non_whitespace_after,  # simple start-strings
               [r'\*\*',                # strong
                r'\*(?!\*)',            # emphasis but not strong
                r'``',                  # literal
                r'_`',                  # inline internal target
                r'\|(?!\|)']            # substitution reference
               ),
              ('whole', '', end_string_suffix, # whole constructs
               [# reference name & end-string
                r'(?P<refname>%s)(?P<refend>__?)' % simplename,
                ('footnotelabel', r'\[', r'(?P<fnend>\]_)',
                 [r'[0-9]+',               # manually numbered
                  r'\#(%s)?' % simplename, # auto-numbered (w/ label?)
                  r'\*',                   # auto-symbol
                  r'(?P<citationlabel>%s)' % simplename] # citation reference
                 )
                ]
               ),
              ('backquote',             # interpreted text or phrase reference
               '(?P<role>(:%s:)?)' % simplename, # optional role
               non_whitespace_after,
               ['`(?!`)']               # but not literal
               )
              ]
             )
    patterns = Struct(
          initial=build_regexp(parts),
          emphasis=re.compile(non_whitespace_escape_before
                              + r'(\*)' + end_string_suffix),
          strong=re.compile(non_whitespace_escape_before
                            + r'(\*\*)' + end_string_suffix),
          interpreted_or_phrase_ref=re.compile(
              r"""
              %(non_whitespace_escape_before)s
              (
                `
                (?P<suffix>
                  (?P<role>:%(simplename)s:)?
                  (?P<refend>__?)?
                )
              )
              %(end_string_suffix)s
              """ % locals(), re.VERBOSE | re.UNICODE),
          embedded_uri=re.compile(
              r"""
              (
                (?:[ \n]+|^)            # spaces or beginning of line/string
                <                       # open bracket
                %(non_whitespace_after)s
                ([^<>\x00]+)            # anything but angle brackets & nulls
                %(non_whitespace_before)s
                >                       # close bracket w/o whitespace before
              )
              $                         # end of string
              """ % locals(), re.VERBOSE),
          literal=re.compile(non_whitespace_before + '(``)'
                             + end_string_suffix),
          target=re.compile(non_whitespace_escape_before
                            + r'(`)' + end_string_suffix),
          substitution_ref=re.compile(non_whitespace_escape_before
                                      + r'(\|_{0,2})'
                                      + end_string_suffix),
          email=re.compile(email_pattern % locals() + '$', re.VERBOSE),
          uri=re.compile(
                (r"""
                %(start_string_prefix)s
                (?P<whole>
                  (?P<absolute>           # absolute URI
                    (?P<scheme>             # scheme (http, ftp, mailto)
                      [a-zA-Z][a-zA-Z0-9.+-]*
                    )
                    :
                    (
                      (                       # either:
                        (//?)?                  # hierarchical URI
                        %(uric)s*               # URI characters
                        %(uri_end)s             # final URI char
                      )
                      (                       # optional query
                        \?%(uric)s*
                        %(uri_end)s
                      )?
                      (                       # optional fragment
                        \#%(uric)s*
                        %(uri_end)s
                      )?
                    )
                  )
                |                       # *OR*
                  (?P<email>              # email address
                    """ + email_pattern + r"""
                  )
                )
                %(end_string_suffix)s
                """) % locals(), re.VERBOSE),
          pep=re.compile(
                r"""
                %(start_string_prefix)s
                (
                  (pep-(?P<pepnum1>\d+)(.txt)?) # reference to source file
                |
                  (PEP\s+(?P<pepnum2>\d+))      # reference by name
                )
                %(end_string_suffix)s""" % locals(), re.VERBOSE),
          rfc=re.compile(
                r"""
                %(start_string_prefix)s
                (RFC(-|\s+)?(?P<rfcnum>\d+))
                %(end_string_suffix)s""" % locals(), re.VERBOSE))

    def quoted_start(self, match):
        """Return 1 if inline markup start-string is 'quoted', 0 if not."""
        string = match.string
        start = match.start()
        end = match.end()
        if start == 0:                  # start-string at beginning of text
            return 0
        prestart = string[start - 1]
        try:
            poststart = string[end]
            if self.openers.index(prestart) \
                  == self.closers.index(poststart):   # quoted
                return 1
        except IndexError:              # start-string at end of text
            return 1
        except ValueError:              # not quoted
            pass
        return 0

    def inline_obj(self, match, lineno, end_pattern, nodeclass,
                   restore_backslashes=0):
        string = match.string
        matchstart = match.start('start')
        matchend = match.end('start')
        if self.quoted_start(match):
            return (string[:matchend], [], string[matchend:], [], '')
        endmatch = end_pattern.search(string[matchend:])
        if endmatch and endmatch.start(1):  # 1 or more chars
            text = unescape(endmatch.string[:endmatch.start(1)],
                            restore_backslashes)
            textend = matchend + endmatch.end(1)
            rawsource = unescape(string[matchstart:textend], 1)
            return (string[:matchstart], [nodeclass(rawsource, text)],
                    string[textend:], [], endmatch.group(1))
        msg = self.reporter.warning(
              'Inline %s start-string without end-string.'
              % nodeclass.__name__, line=lineno)
        text = unescape(string[matchstart:matchend], 1)
        rawsource = unescape(string[matchstart:matchend], 1)
        prb = self.problematic(text, rawsource, msg)
        return string[:matchstart], [prb], string[matchend:], [msg], ''

    def problematic(self, text, rawsource, message):
        msgid = self.document.set_id(message, self.parent)
        problematic = nodes.problematic(rawsource, text, refid=msgid)
        prbid = self.document.set_id(problematic)
        message.add_backref(prbid)
        return problematic

    def emphasis(self, match, lineno):
        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
              match, lineno, self.patterns.emphasis, nodes.emphasis)
        return before, inlines, remaining, sysmessages

    def strong(self, match, lineno):
        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
              match, lineno, self.patterns.strong, nodes.strong)
        return before, inlines, remaining, sysmessages

    def interpreted_or_phrase_ref(self, match, lineno):
        end_pattern = self.patterns.interpreted_or_phrase_ref
        string = match.string
        matchstart = match.start('backquote')
        matchend = match.end('backquote')
        rolestart = match.start('role')
        role = match.group('role')
        position = ''
        if role:
            role = role[1:-1]
            position = 'prefix'
        elif self.quoted_start(match):
            return (string[:matchend], [], string[matchend:], [])
        endmatch = end_pattern.search(string[matchend:])
        if endmatch and endmatch.start(1):  # 1 or more chars
            textend = matchend + endmatch.end()
            if endmatch.group('role'):
                if role:
                    msg = self.reporter.warning(
                        'Multiple roles in interpreted text (both '
                        'prefix and suffix present; only one allowed).',
                        line=lineno)
                    text = unescape(string[rolestart:textend], 1)
                    prb = self.problematic(text, text, msg)
                    return string[:rolestart], [prb], string[textend:], [msg]
                role = endmatch.group('suffix')[1:-1]
                position = 'suffix'
            escaped = endmatch.string[:endmatch.start(1)]
            rawsource = unescape(string[matchstart:textend], 1)
            if rawsource[-1:] == '_':
                if role:
                    msg = self.reporter.warning(
                          'Mismatch: both interpreted text role %s and '
                          'reference suffix.' % position, line=lineno)
                    text = unescape(string[rolestart:textend], 1)
                    prb = self.problematic(text, text, msg)
                    return string[:rolestart], [prb], string[textend:], [msg]
                return self.phrase_ref(string[:matchstart], string[textend:],
                                       rawsource, escaped, unescape(escaped))
            else:
                rawsource = unescape(string[rolestart:textend], 1)
                nodelist, messages = self.interpreted(rawsource, escaped, role,
                                                      lineno)
                return (string[:rolestart], nodelist,
                        string[textend:], messages)
        msg = self.reporter.warning(
              'Inline interpreted text or phrase reference start-string '
              'without end-string.', line=lineno)
        text = unescape(string[matchstart:matchend], 1)
        prb = self.problematic(text, text, msg)
        return string[:matchstart], [prb], string[matchend:], [msg]

    def phrase_ref(self, before, after, rawsource, escaped, text):
        match = self.patterns.embedded_uri.search(escaped)
        if match:
            text = unescape(escaped[:match.start(0)])
            uri_text = match.group(2)
            uri = ''.join(uri_text.split())
            uri = self.adjust_uri(uri)
            if uri:
                target = nodes.target(match.group(1), refuri=uri)
            else:
                raise ApplicationError('problem with URI: %r' % uri_text)
            if not text:
                text = uri
        else:
            target = None
        refname = normalize_name(text)
        reference = nodes.reference(rawsource, text,
                                    name=whitespace_normalize_name(text))
        node_list = [reference]
        if rawsource[-2:] == '__':
            if target:
                reference['refuri'] = uri
            else:
                reference['anonymous'] = 1
                self.document.note_anonymous_ref(reference)
        else:
            if target:
                reference['refuri'] = uri
                target['names'].append(refname)
                self.document.note_external_target(target)
                self.document.note_explicit_target(target, self.parent)
                node_list.append(target)
            else:
                reference['refname'] = refname
                self.document.note_refname(reference)
        return before, node_list, after, []

    def adjust_uri(self, uri):
        match = self.patterns.email.match(uri)
        if match:
            return 'mailto:' + uri
        else:
            return uri

    def interpreted(self, rawsource, text, role, lineno):
        role_fn, messages = roles.role(role, self.language, lineno,
                                       self.reporter)
        if role_fn:
            nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
            return nodes, messages + messages2
        else:
            msg = self.reporter.error(
                'Unknown interpreted text role "%s".' % role,
                line=lineno)
            return ([self.problematic(rawsource, rawsource, msg)],
                    messages + [msg])

    def literal(self, match, lineno):
        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
              match, lineno, self.patterns.literal, nodes.literal,
              restore_backslashes=1)
        return before, inlines, remaining, sysmessages

    def inline_internal_target(self, match, lineno):
        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
              match, lineno, self.patterns.target, nodes.target)
        if inlines and isinstance(inlines[0], nodes.target):
            assert len(inlines) == 1
            target = inlines[0]
            name = normalize_name(target.astext())
            target['names'].append(name)
            self.document.note_explicit_target(target, self.parent)
        return before, inlines, remaining, sysmessages

    def substitution_reference(self, match, lineno):
        before, inlines, remaining, sysmessages, endstring = self.inline_obj(
              match, lineno, self.patterns.substitution_ref,
              nodes.substitution_reference)
        if len(inlines) == 1:
            subref_node = inlines[0]
            if isinstance(subref_node, nodes.substitution_reference):
                subref_text = subref_node.astext()
                self.document.note_substitution_ref(subref_node, subref_text)
                if endstring[-1:] == '_':
                    reference_node = nodes.reference(
                        '|%s%s' % (subref_text, endstring), '')
                    if endstring[-2:] == '__':
                        reference_node['anonymous'] = 1
                        self.document.note_anonymous_ref(
                              reference_node)
                    else:
                        reference_node['refname'] = normalize_name(subref_text)
                        self.document.note_refname(reference_node)
                    reference_node += subref_node
                    inlines = [reference_node]
        return before, inlines, remaining, sysmessages

    def footnote_reference(self, match, lineno):
        """
        Handles `nodes.footnote_reference` and `nodes.citation_reference`
        elements.
        """
        label = match.group('footnotelabel')
        refname = normalize_name(label)
        string = match.string
        before = string[:match.start('whole')]
        remaining = string[match.end('whole'):]
        if match.group('citationlabel'):
            refnode = nodes.citation_reference('[%s]_' % label,
                                               refname=refname)
            refnode += nodes.Text(label)
            self.document.note_citation_ref(refnode)
        else:
            refnode = nodes.footnote_reference('[%s]_' % label)
            if refname[0] == '#':
                refname = refname[1:]
                refnode['auto'] = 1
                self.document.note_autofootnote_ref(refnode)
            elif refname == '*':
                refname = ''
                refnode['auto'] = '*'
                self.document.note_symbol_footnote_ref(
                      refnode)
            else:
                refnode += nodes.Text(label)
            if refname:
                refnode['refname'] = refname
                self.document.note_footnote_ref(refnode)
            if utils.get_trim_footnote_ref_space(self.document.settings):
                before = before.rstrip()
        return (before, [refnode], remaining, [])

    def reference(self, match, lineno, anonymous=None):
        referencename = match.group('refname')
        refname = normalize_name(referencename)
        referencenode = nodes.reference(
            referencename + match.group('refend'), referencename,
            name=whitespace_normalize_name(referencename))
        if anonymous:
            referencenode['anonymous'] = 1
            self.document.note_anonymous_ref(referencenode)
        else:
            referencenode['refname'] = refname
            self.document.note_refname(referencenode)
        string = match.string
        matchstart = match.start('whole')
        matchend = match.end('whole')
        return (string[:matchstart], [referencenode], string[matchend:], [])

    def anonymous_reference(self, match, lineno):
        return self.reference(match, lineno, anonymous=1)

    def standalone_uri(self, match, lineno):
        if not match.group('scheme') or urischemes.schemes.has_key(
              match.group('scheme').lower()):
            if match.group('email'):
                addscheme = 'mailto:'
            else:
                addscheme = ''
            text = match.group('whole')
            unescaped = unescape(text, 0)
            return [nodes.reference(unescape(text, 1), unescaped,
                                    refuri=addscheme + unescaped)]
        else:                   # not a valid scheme
            raise MarkupMismatch

    pep_url = 'pep-%04d.html'

    def pep_reference(self, match, lineno):
        text = match.group(0)
        if text.startswith('pep-'):
            pepnum = int(match.group('pepnum1'))
        elif text.startswith('PEP'):
            pepnum = int(match.group('pepnum2'))
        else:
            raise MarkupMismatch
        ref = self.document.settings.pep_base_url + self.pep_url % pepnum
        unescaped = unescape(text, 0)
        return [nodes.reference(unescape(text, 1), unescaped, refuri=ref)]

    rfc_url = 'rfc%d.html'

    def rfc_reference(self, match, lineno):
        text = match.group(0)
        if text.startswith('RFC'):
            rfcnum = int(match.group('rfcnum'))
            ref = self.document.settings.rfc_base_url + self.rfc_url % rfcnum
        else:
            raise MarkupMismatch
        unescaped = unescape(text, 0)
        return [nodes.reference(unescape(text, 1), unescaped, refuri=ref)]

    def implicit_inline(self, text, lineno):
        """
        Check each of the patterns in `self.implicit_dispatch` for a match,
        and dispatch to the stored method for the pattern.  Recursively check
        the text before and after the match.  Return a list of `nodes.Text`
        and inline element nodes.
        """
        if not text:
            return []
        for pattern, method in self.implicit_dispatch:
            match = pattern.search(text)
            if match:
                try:
                    # Must recurse on strings before *and* after the match;
                    # there may be multiple patterns.
                    return (self.implicit_inline(text[:match.start()], lineno)
                            + method(match, lineno) +
                            self.implicit_inline(text[match.end():], lineno))
                except MarkupMismatch:
                    pass
        return [nodes.Text(unescape(text), rawsource=unescape(text, 1))]

    dispatch = {'*': emphasis,
                '**': strong,
                '`': interpreted_or_phrase_ref,
                '``': literal,
                '_`': inline_internal_target,
                ']_': footnote_reference,
                '|': substitution_reference,
                '_': reference,
                '__': anonymous_reference}


class Body(RSTState):

    """
    Generic classifier of the first line of a block.
    """

    enum = Struct()
    """Enumerated list parsing information."""

    enum.formatinfo = {
          'parens': Struct(prefix='(', suffix=')', start=1, end=-1),
          'rparen': Struct(prefix='', suffix=')', start=0, end=-1),
          'period': Struct(prefix='', suffix='.', start=0, end=-1)}
    enum.formats = enum.formatinfo.keys()
    enum.sequences = ['arabic', 'loweralpha', 'upperalpha',
                      'lowerroman', 'upperroman'] # ORDERED!
    enum.sequencepats = {'arabic': '[0-9]+',
                         'loweralpha': '[a-z]',
                         'upperalpha': '[A-Z]',
                         'lowerroman': '[ivxlcdm]+',
                         'upperroman': '[IVXLCDM]+',}
    enum.converters = {'arabic': int,
                       'loweralpha':
                       lambda s, zero=(ord('a')-1): ord(s) - zero,
                       'upperalpha':
                       lambda s, zero=(ord('A')-1): ord(s) - zero,
                       'lowerroman':
                       lambda s: roman.fromRoman(s.upper()),
                       'upperroman': roman.fromRoman}

    enum.sequenceregexps = {}
    for sequence in enum.sequences:
        enum.sequenceregexps[sequence] = re.compile(
              enum.sequencepats[sequence] + '$')

    grid_table_top_pat = re.compile(r'\+-[-+]+-\+ *$')
    """Matches the top (& bottom) of a full table)."""

    simple_table_top_pat = re.compile('=+( +=+)+ *$')
    """Matches the top of a simple table."""

    simple_table_border_pat = re.compile('=+[ =]*$')
    """Matches the bottom & header bottom of a simple table."""

    pats = {}
    """Fragments of patterns used by transitions."""

    pats['nonalphanum7bit'] = '[!-/:-@[-`{-~]'
    pats['alpha'] = '[a-zA-Z]'
    pats['alphanum'] = '[a-zA-Z0-9]'
    pats['alphanumplus'] = '[a-zA-Z0-9_-]'
    pats['enum'] = ('(%(arabic)s|%(loweralpha)s|%(upperalpha)s|%(lowerroman)s'
                    '|%(upperroman)s|#)' % enum.sequencepats)
    pats['optname'] = '%(alphanum)s%(alphanumplus)s*' % pats
    # @@@ Loosen up the pattern?  Allow Unicode?
    pats['optarg'] = '(%(alpha)s%(alphanumplus)s*|<[^<>]+>)' % pats
    pats['shortopt'] = r'(-|\+)%(alphanum)s( ?%(optarg)s)?' % pats
    pats['longopt'] = r'(--|/)%(optname)s([ =]%(optarg)s)?' % pats
    pats['option'] = r'(%(shortopt)s|%(longopt)s)' % pats

    for format in enum.formats:
        pats[format] = '(?P<%s>%s%s%s)' % (
              format, re.escape(enum.formatinfo[format].prefix),
              pats['enum'], re.escape(enum.formatinfo[format].suffix))

    patterns = {
          'bullet': r'[-+*]( +|$)',
          'enumerator': r'(%(parens)s|%(rparen)s|%(period)s)( +|$)' % pats,
          'field_marker': r':[^: ]([^:]*[^: ])?:( +|$)',
          'option_marker': r'%(option)s(, %(option)s)*(  +| ?$)' % pats,
          'doctest': r'>>>( +|$)',
          'line_block': r'\|( +|$)',
          'grid_table_top': grid_table_top_pat,
          'simple_table_top': simple_table_top_pat,
          'explicit_markup': r'\.\.( +|$)',
          'anonymous': r'__( +|$)',
          'line': r'(%(nonalphanum7bit)s)\1* *$' % pats,
          'text': r''}
    initial_transitions = (
          'bullet',
          'enumerator',
          'field_marker',
          'option_marker',
          'doctest',
          'line_block',
          'grid_table_top',
          'simple_table_top',
          'explicit_markup',
          'anonymous',
          'line',
          'text')

    def indent(self, match, context, next_state):
        """Block quote."""
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_indented()
        blockquote, messages = self.block_quote(indented, line_offset)
        self.parent += blockquote
        self.parent += messages
        if not blank_finish:
            self.parent += self.unindent_warning('Block quote')
        return context, next_state, []

    def block_quote(self, indented, line_offset):
        blockquote_lines, attribution_lines, attribution_offset = \
              self.check_attribution(indented, line_offset)
        blockquote = nodes.block_quote()
        self.nested_parse(blockquote_lines, line_offset, blockquote)
        messages = []
        if attribution_lines:
            attribution, messages = self.parse_attribution(attribution_lines,
                                                           attribution_offset)
            blockquote += attribution
        return blockquote, messages

    # u'\u2014' is an em-dash:
    attribution_pattern = re.compile(ur'(---?(?!-)|\u2014) *(?=[^ \n])')

    def check_attribution(self, indented, line_offset):
        """
        Check for an attribution in the last contiguous block of `indented`.

        * First line after last blank line must begin with "--" (etc.).
        * Every line after that must have consistent indentation.

        Return a 3-tuple: (block quote lines, attribution lines,
        attribution offset).
        """
        blank = None
        nonblank_seen = None
        indent = 0
        for i in range(len(indented) - 1, 0, -1): # don't check first line
            this_line_blank = not indented[i].strip()
            if nonblank_seen and this_line_blank:
                match = self.attribution_pattern.match(indented[i + 1])
                if match:
                    blank = i
                break
            elif not this_line_blank:
                nonblank_seen = 1
        if blank and len(indented) - blank > 2: # multi-line attribution
            indent = (len(indented[blank + 2])
                      - len(indented[blank + 2].lstrip()))
            for j in range(blank + 3, len(indented)):
                if indent != (len(indented[j])
                              - len(indented[j].lstrip())): # bad shape
                    blank = None
                    break
        if blank:
            a_lines = indented[blank + 1:]
            a_lines.trim_left(match.end(), end=1)
            a_lines.trim_left(indent, start=1)
            return (indented[:blank], a_lines, line_offset + blank + 1)
        else:
            return (indented, None, None)

    def parse_attribution(self, indented, line_offset):
        text = '\n'.join(indented).rstrip()
        lineno = self.state_machine.abs_line_number() + line_offset
        textnodes, messages = self.inline_text(text, lineno)
        node = nodes.attribution(text, '', *textnodes)
        node.line = lineno
        return node, messages

    def bullet(self, match, context, next_state):
        """Bullet list item."""
        bulletlist = nodes.bullet_list()
        self.parent += bulletlist
        bulletlist['bullet'] = match.string[0]
        i, blank_finish = self.list_item(match.end())
        bulletlist += i
        offset = self.state_machine.line_offset + 1   # next line
        new_line_offset, blank_finish = self.nested_list_parse(
              self.state_machine.input_lines[offset:],
              input_offset=self.state_machine.abs_line_offset() + 1,
              node=bulletlist, initial_state='BulletList',
              blank_finish=blank_finish)
        self.goto_line(new_line_offset)
        if not blank_finish:
            self.parent += self.unindent_warning('Bullet list')
        return [], next_state, []

    def list_item(self, indent):
        indented, line_offset, blank_finish = \
              self.state_machine.get_known_indented(indent)
        listitem = nodes.list_item('\n'.join(indented))
        if indented:
            self.nested_parse(indented, input_offset=line_offset,
                              node=listitem)
        return listitem, blank_finish

    def enumerator(self, match, context, next_state):
        """Enumerated List Item"""
        format, sequence, text, ordinal = self.parse_enumerator(match)
        if not self.is_enumerated_list_item(ordinal, sequence, format):
            raise statemachine.TransitionCorrection('text')
        enumlist = nodes.enumerated_list()
        self.parent += enumlist
        if sequence == '#':
            enumlist['enumtype'] = 'arabic'
        else:
            enumlist['enumtype'] = sequence
        enumlist['prefix'] = self.enum.formatinfo[format].prefix
        enumlist['suffix'] = self.enum.formatinfo[format].suffix
        if ordinal != 1:
            enumlist['start'] = ordinal
            msg = self.reporter.info(
                'Enumerated list start value not ordinal-1: "%s" (ordinal %s)'
                % (text, ordinal), line=self.state_machine.abs_line_number())
            self.parent += msg
        listitem, blank_finish = self.list_item(match.end())
        enumlist += listitem
        offset = self.state_machine.line_offset + 1   # next line
        newline_offset, blank_finish = self.nested_list_parse(
              self.state_machine.input_lines[offset:],
              input_offset=self.state_machine.abs_line_offset() + 1,
              node=enumlist, initial_state='EnumeratedList',
              blank_finish=blank_finish,
              extra_settings={'lastordinal': ordinal,
                              'format': format,
                              'auto': sequence == '#'})
        self.goto_line(newline_offset)
        if not blank_finish:
            self.parent += self.unindent_warning('Enumerated list')
        return [], next_state, []

    def parse_enumerator(self, match, expected_sequence=None):
        """
        Analyze an enumerator and return the results.

        :Return:
            - the enumerator format ('period', 'parens', or 'rparen'),
            - the sequence used ('arabic', 'loweralpha', 'upperroman', etc.),
            - the text of the enumerator, stripped of formatting, and
            - the ordinal value of the enumerator ('a' -> 1, 'ii' -> 2, etc.;
              ``None`` is returned for invalid enumerator text).

        The enumerator format has already been determined by the regular
        expression match. If `expected_sequence` is given, that sequence is
        tried first. If not, we check for Roman numeral 1. This way,
        single-character Roman numerals (which are also alphabetical) can be
        matched. If no sequence has been matched, all sequences are checked in
        order.
        """
        groupdict = match.groupdict()
        sequence = ''
        for format in self.enum.formats:
            if groupdict[format]:       # was this the format matched?
                break                   # yes; keep `format`
        else:                           # shouldn't happen
            raise ParserError('enumerator format not matched')
        text = groupdict[format][self.enum.formatinfo[format].start
                                 :self.enum.formatinfo[format].end]
        if text == '#':
            sequence = '#'
        elif expected_sequence:
            try:
                if self.enum.sequenceregexps[expected_sequence].match(text):
                    sequence = expected_sequence
            except KeyError:            # shouldn't happen
                raise ParserError('unknown enumerator sequence: %s'
                                  % sequence)
        elif text == 'i':
            sequence = 'lowerroman'
        elif text == 'I':
            sequence = 'upperroman'
        if not sequence:
            for sequence in self.enum.sequences:
                if self.enum.sequenceregexps[sequence].match(text):
                    break
            else:                       # shouldn't happen
                raise ParserError('enumerator sequence not matched')
        if sequence == '#':
            ordinal = 1
        else:
            try:
                ordinal = self.enum.converters[sequence](text)
            except roman.InvalidRomanNumeralError:
                ordinal = None
        return format, sequence, text, ordinal

    def is_enumerated_list_item(self, ordinal, sequence, format):
        """
        Check validity based on the ordinal value and the second line.

        Return true iff the ordinal is valid and the second line is blank,
        indented, or starts with the next enumerator or an auto-enumerator.
        """
        if ordinal is None:
            return None
        try:
            next_line = self.state_machine.next_line()
        except EOFError:              # end of input lines
            self.state_machine.previous_line()
            return 1
        else:
            self.state_machine.previous_line()
        if not next_line[:1].strip():   # blank or indented
            return 1
        next_enumerator, auto_enumerator = self.make_enumerator(
            ordinal + 1, sequence, format)
        try:
            if ( next_line.startswith(next_enumerator) or
                 next_line.startswith(auto_enumerator) ):
                return 1
        except TypeError:
            pass
        return None

    def make_enumerator(self, ordinal, sequence, format):
        """
        Construct and return the next enumerated list item marker, and an
        auto-enumerator ("#" instead of the regular enumerator).

        Return ``None`` for invalid (out of range) ordinals.
        """ #"
        if sequence == '#':
            enumerator = '#'
        elif sequence == 'arabic':
            enumerator = str(ordinal)
        else:
            if sequence.endswith('alpha'):
                if ordinal > 26:
                    return None
                enumerator = chr(ordinal + ord('a') - 1)
            elif sequence.endswith('roman'):
                try:
                    enumerator = roman.toRoman(ordinal)
                except roman.RomanError:
                    return None
            else:                       # shouldn't happen
                raise ParserError('unknown enumerator sequence: "%s"'
                                  % sequence)
            if sequence.startswith('lower'):
                enumerator = enumerator.lower()
            elif sequence.startswith('upper'):
                enumerator = enumerator.upper()
            else:                       # shouldn't happen
                raise ParserError('unknown enumerator sequence: "%s"'
                                  % sequence)
        formatinfo = self.enum.formatinfo[format]
        next_enumerator = (formatinfo.prefix + enumerator + formatinfo.suffix
                           + ' ')
        auto_enumerator = formatinfo.prefix + '#' + formatinfo.suffix + ' '
        return next_enumerator, auto_enumerator

    def field_marker(self, match, context, next_state):
        """Field list item."""
        field_list = nodes.field_list()
        self.parent += field_list
        field, blank_finish = self.field(match)
        field_list += field
        offset = self.state_machine.line_offset + 1   # next line
        newline_offset, blank_finish = self.nested_list_parse(
              self.state_machine.input_lines[offset:],
              input_offset=self.state_machine.abs_line_offset() + 1,
              node=field_list, initial_state='FieldList',
              blank_finish=blank_finish)
        self.goto_line(newline_offset)
        if not blank_finish:
            self.parent += self.unindent_warning('Field list')
        return [], next_state, []

    def field(self, match):
        name = self.parse_field_marker(match)
        lineno = self.state_machine.abs_line_number()
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end())
        field_node = nodes.field()
        field_node.line = lineno
        name_nodes, name_messages = self.inline_text(name, lineno)
        field_node += nodes.field_name(name, '', *name_nodes)
        field_body = nodes.field_body('\n'.join(indented), *name_messages)
        field_node += field_body
        if indented:
            self.parse_field_body(indented, line_offset, field_body)
        return field_node, blank_finish

    def parse_field_marker(self, match):
        """Extract & return field name from a field marker match."""
        field = match.string[1:]        # strip off leading ':'
        field = field[:field.find(':')] # strip off trailing ':' etc.
        return field

    def parse_field_body(self, indented, offset, node):
        self.nested_parse(indented, input_offset=offset, node=node)

    def option_marker(self, match, context, next_state):
        """Option list item."""
        optionlist = nodes.option_list()
        try:
            listitem, blank_finish = self.option_list_item(match)
        except MarkupError, (message, lineno):
            # This shouldn't happen; pattern won't match.
            msg = self.reporter.error(
                'Invalid option list marker: %s' % message, line=lineno)
            self.parent += msg
            indented, indent, line_offset, blank_finish = \
                  self.state_machine.get_first_known_indented(match.end())
            blockquote, messages = self.block_quote(indented, line_offset)
            self.parent += blockquote
            self.parent += messages
            if not blank_finish:
                self.parent += self.unindent_warning('Option list')
            return [], next_state, []
        self.parent += optionlist
        optionlist += listitem
        offset = self.state_machine.line_offset + 1   # next line
        newline_offset, blank_finish = self.nested_list_parse(
              self.state_machine.input_lines[offset:],
              input_offset=self.state_machine.abs_line_offset() + 1,
              node=optionlist, initial_state='OptionList',
              blank_finish=blank_finish)
        self.goto_line(newline_offset)
        if not blank_finish:
            self.parent += self.unindent_warning('Option list')
        return [], next_state, []

    def option_list_item(self, match):
        offset = self.state_machine.abs_line_offset()
        options = self.parse_option_marker(match)
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end())
        if not indented:                # not an option list item
            self.goto_line(offset)
            raise statemachine.TransitionCorrection('text')
        option_group = nodes.option_group('', *options)
        description = nodes.description('\n'.join(indented))
        option_list_item = nodes.option_list_item('', option_group,
                                                  description)
        if indented:
            self.nested_parse(indented, input_offset=line_offset,
                              node=description)
        return option_list_item, blank_finish

    def parse_option_marker(self, match):
        """
        Return a list of `node.option` and `node.option_argument` objects,
        parsed from an option marker match.

        :Exception: `MarkupError` for invalid option markers.
        """
        optlist = []
        optionstrings = match.group().rstrip().split(', ')
        for optionstring in optionstrings:
            tokens = optionstring.split()
            delimiter = ' '
            firstopt = tokens[0].split('=')
            if len(firstopt) > 1:
                # "--opt=value" form
                tokens[:1] = firstopt
                delimiter = '='
            elif (len(tokens[0]) > 2
                  and ((tokens[0].startswith('-')
                        and not tokens[0].startswith('--'))
                       or tokens[0].startswith('+'))):
                # "-ovalue" form
                tokens[:1] = [tokens[0][:2], tokens[0][2:]]
                delimiter = ''
            if len(tokens) > 1 and (tokens[1].startswith('<')
                                    and tokens[-1].endswith('>')):
                # "-o <value1 value2>" form; join all values into one token
                tokens[1:] = [' '.join(tokens[1:])]
            if 0 < len(tokens) <= 2:
                option = nodes.option(optionstring)
                option += nodes.option_string(tokens[0], tokens[0])
                if len(tokens) > 1:
                    option += nodes.option_argument(tokens[1], tokens[1],
                                                    delimiter=delimiter)
                optlist.append(option)
            else:
                raise MarkupError(
                    'wrong number of option tokens (=%s), should be 1 or 2: '
                    '"%s"' % (len(tokens), optionstring),
                    self.state_machine.abs_line_number() + 1)
        return optlist

    def doctest(self, match, context, next_state):
        data = '\n'.join(self.state_machine.get_text_block())
        self.parent += nodes.doctest_block(data, data)
        return [], next_state, []

    def line_block(self, match, context, next_state):
        """First line of a line block."""
        block = nodes.line_block()
        self.parent += block
        lineno = self.state_machine.abs_line_number()
        line, messages, blank_finish = self.line_block_line(match, lineno)
        block += line
        self.parent += messages
        if not blank_finish:
            offset = self.state_machine.line_offset + 1   # next line
            new_line_offset, blank_finish = self.nested_list_parse(
                  self.state_machine.input_lines[offset:],
                  input_offset=self.state_machine.abs_line_offset() + 1,
                  node=block, initial_state='LineBlock',
                  blank_finish=0)
            self.goto_line(new_line_offset)
        if not blank_finish:
            self.parent += self.reporter.warning(
                'Line block ends without a blank line.',
                line=(self.state_machine.abs_line_number() + 1))
        if len(block):
            if block[0].indent is None:
                block[0].indent = 0
            self.nest_line_block_lines(block)
        return [], next_state, []

    def line_block_line(self, match, lineno):
        """Return one line element of a line_block."""
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end(),
                                                          until_blank=1)
        text = u'\n'.join(indented)
        text_nodes, messages = self.inline_text(text, lineno)
        line = nodes.line(text, '', *text_nodes)
        if match.string.rstrip() != '|': # not empty
            line.indent = len(match.group(1)) - 1
        return line, messages, blank_finish

    def nest_line_block_lines(self, block):
        for index in range(1, len(block)):
            if block[index].indent is None:
                block[index].indent = block[index - 1].indent
        self.nest_line_block_segment(block)

    def nest_line_block_segment(self, block):
        indents = [item.indent for item in block]
        least = min(indents)
        new_items = []
        new_block = nodes.line_block()
        for item in block:
            if item.indent > least:
                new_block.append(item)
            else:
                if len(new_block):
                    self.nest_line_block_segment(new_block)
                    new_items.append(new_block)
                    new_block = nodes.line_block()
                new_items.append(item)
        if len(new_block):
            self.nest_line_block_segment(new_block)
            new_items.append(new_block)
        block[:] = new_items

    def grid_table_top(self, match, context, next_state):
        """Top border of a full table."""
        return self.table_top(match, context, next_state,
                              self.isolate_grid_table,
                              tableparser.GridTableParser)

    def simple_table_top(self, match, context, next_state):
        """Top border of a simple table."""
        return self.table_top(match, context, next_state,
                              self.isolate_simple_table,
                              tableparser.SimpleTableParser)

    def table_top(self, match, context, next_state,
                  isolate_function, parser_class):
        """Top border of a generic table."""
        nodelist, blank_finish = self.table(isolate_function, parser_class)
        self.parent += nodelist
        if not blank_finish:
            msg = self.reporter.warning(
                'Blank line required after table.',
                line=self.state_machine.abs_line_number() + 1)
            self.parent += msg
        return [], next_state, []

    def table(self, isolate_function, parser_class):
        """Parse a table."""
        block, messages, blank_finish = isolate_function()
        if block:
            try:
                parser = parser_class()
                tabledata = parser.parse(block)
                tableline = (self.state_machine.abs_line_number() - len(block)
                             + 1)
                table = self.build_table(tabledata, tableline)
                nodelist = [table] + messages
            except tableparser.TableMarkupError, detail:
                nodelist = self.malformed_table(
                    block, ' '.join(detail.args)) + messages
        else:
            nodelist = messages
        return nodelist, blank_finish

    def isolate_grid_table(self):
        messages = []
        blank_finish = 1
        try:
            block = self.state_machine.get_text_block(flush_left=1)
        except statemachine.UnexpectedIndentationError, instance:
            block, source, lineno = instance.args
            messages.append(self.reporter.error('Unexpected indentation.',
                                                source=source, line=lineno))
            blank_finish = 0
        block.disconnect()
        width = len(block[0].strip())
        for i in range(len(block)):
            block[i] = block[i].strip()
            if block[i][0] not in '+|': # check left edge
                blank_finish = 0
                self.state_machine.previous_line(len(block) - i)
                del block[i:]
                break
        if not self.grid_table_top_pat.match(block[-1]): # find bottom
            blank_finish = 0
            # from second-last to third line of table:
            for i in range(len(block) - 2, 1, -1):
                if self.grid_table_top_pat.match(block[i]):
                    self.state_machine.previous_line(len(block) - i + 1)
                    del block[i+1:]
                    break
            else:
                messages.extend(self.malformed_table(block))
                return [], messages, blank_finish
        for i in range(len(block)):     # check right edge
            if len(block[i]) != width or block[i][-1] not in '+|':
                messages.extend(self.malformed_table(block))
                return [], messages, blank_finish
        return block, messages, blank_finish

    def isolate_simple_table(self):
        start = self.state_machine.line_offset
        lines = self.state_machine.input_lines
        limit = len(lines) - 1
        toplen = len(lines[start].strip())
        pattern_match = self.simple_table_border_pat.match
        found = 0
        found_at = None
        i = start + 1
        while i <= limit:
            line = lines[i]
            match = pattern_match(line)
            if match:
                if len(line.strip()) != toplen:
                    self.state_machine.next_line(i - start)
                    messages = self.malformed_table(
                        lines[start:i+1], 'Bottom/header table border does '
                        'not match top border.')
                    return [], messages, i == limit or not lines[i+1].strip()
                found += 1
                found_at = i
                if found == 2 or i == limit or not lines[i+1].strip():
                    end = i
                    break
            i += 1
        else:                           # reached end of input_lines
            if found:
                extra = ' or no blank line after table bottom'
                self.state_machine.next_line(found_at - start)
                block = lines[start:found_at+1]
            else:
                extra = ''
                self.state_machine.next_line(i - start - 1)
                block = lines[start:]
            messages = self.malformed_table(
                block, 'No bottom table border found%s.' % extra)
            return [], messages, not extra
        self.state_machine.next_line(end - start)
        block = lines[start:end+1]
        return block, [], end == limit or not lines[end+1].strip()

    def malformed_table(self, block, detail=''):
        data = '\n'.join(block)
        message = 'Malformed table.'
        lineno = self.state_machine.abs_line_number() - len(block) + 1
        if detail:
            message += '\n' + detail
        error = self.reporter.error(message, nodes.literal_block(data, data),
                                    line=lineno)
        return [error]

    def build_table(self, tabledata, tableline, stub_columns=0):
        colwidths, headrows, bodyrows = tabledata
        table = nodes.table()
        tgroup = nodes.tgroup(cols=len(colwidths))
        table += tgroup
        for colwidth in colwidths:
            colspec = nodes.colspec(colwidth=colwidth)
            if stub_columns:
                colspec.attributes['stub'] = 1
                stub_columns -= 1
            tgroup += colspec
        if headrows:
            thead = nodes.thead()
            tgroup += thead
            for row in headrows:
                thead += self.build_table_row(row, tableline)
        tbody = nodes.tbody()
        tgroup += tbody
        for row in bodyrows:
            tbody += self.build_table_row(row, tableline)
        return table

    def build_table_row(self, rowdata, tableline):
        row = nodes.row()
        for cell in rowdata:
            if cell is None:
                continue
            morerows, morecols, offset, cellblock = cell
            attributes = {}
            if morerows:
                attributes['morerows'] = morerows
            if morecols:
                attributes['morecols'] = morecols
            entry = nodes.entry(**attributes)
            row += entry
            if ''.join(cellblock):
                self.nested_parse(cellblock, input_offset=tableline+offset,
                                  node=entry)
        return row


    explicit = Struct()
    """Patterns and constants used for explicit markup recognition."""

    explicit.patterns = Struct(
          target=re.compile(r"""
                            (
                              _               # anonymous target
                            |               # *OR*
                              (?P<quote>`?)   # optional open quote
                              (?![ `])        # first char. not space or
                                              # backquote
                              (?P<name>       # reference name
                                .+?
                              )
                              %(non_whitespace_escape_before)s
                              (?P=quote)      # close quote if open quote used
                            )
                            %(non_whitespace_escape_before)s
                            [ ]?            # optional space
                            :               # end of reference name
                            ([ ]+|$)        # followed by whitespace
                            """ % vars(Inliner), re.VERBOSE),
          reference=re.compile(r"""
                               (
                                 (?P<simple>%(simplename)s)_
                               |                  # *OR*
                                 `                  # open backquote
                                 (?![ ])            # not space
                                 (?P<phrase>.+?)    # hyperlink phrase
                                 %(non_whitespace_escape_before)s
                                 `_                 # close backquote,
                                                    # reference mark
                               )
                               $                  # end of string
                               """ % vars(Inliner), re.VERBOSE | re.UNICODE),
          substitution=re.compile(r"""
                                  (
                                    (?![ ])          # first char. not space
                                    (?P<name>.+?)    # substitution text
                                    %(non_whitespace_escape_before)s
                                    \|               # close delimiter
                                  )
                                  ([ ]+|$)           # followed by whitespace
                                  """ % vars(Inliner), re.VERBOSE),)

    def footnote(self, match):
        lineno = self.state_machine.abs_line_number()
        indented, indent, offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end())
        label = match.group(1)
        name = normalize_name(label)
        footnote = nodes.footnote('\n'.join(indented))
        footnote.line = lineno
        if name[0] == '#':              # auto-numbered
            name = name[1:]             # autonumber label
            footnote['auto'] = 1
            if name:
                footnote['names'].append(name)
            self.document.note_autofootnote(footnote)
        elif name == '*':               # auto-symbol
            name = ''
            footnote['auto'] = '*'
            self.document.note_symbol_footnote(footnote)
        else:                           # manually numbered
            footnote += nodes.label('', label)
            footnote['names'].append(name)
            self.document.note_footnote(footnote)
        if name:
            self.document.note_explicit_target(footnote, footnote)
        else:
            self.document.set_id(footnote, footnote)
        if indented:
            self.nested_parse(indented, input_offset=offset, node=footnote)
        return [footnote], blank_finish

    def citation(self, match):
        lineno = self.state_machine.abs_line_number()
        indented, indent, offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end())
        label = match.group(1)
        name = normalize_name(label)
        citation = nodes.citation('\n'.join(indented))
        citation.line = lineno
        citation += nodes.label('', label)
        citation['names'].append(name)
        self.document.note_citation(citation)
        self.document.note_explicit_target(citation, citation)
        if indented:
            self.nested_parse(indented, input_offset=offset, node=citation)
        return [citation], blank_finish

    def hyperlink_target(self, match):
        pattern = self.explicit.patterns.target
        lineno = self.state_machine.abs_line_number()
        block, indent, offset, blank_finish = \
              self.state_machine.get_first_known_indented(
              match.end(), until_blank=1, strip_indent=0)
        blocktext = match.string[:match.end()] + '\n'.join(block)
        block = [escape2null(line) for line in block]
        escaped = block[0]
        blockindex = 0
        while 1:
            targetmatch = pattern.match(escaped)
            if targetmatch:
                break
            blockindex += 1
            try:
                escaped += block[blockindex]
            except IndexError:
                raise MarkupError('malformed hyperlink target.', lineno)
        del block[:blockindex]
        block[0] = (block[0] + ' ')[targetmatch.end()-len(escaped)-1:].strip()
        target = self.make_target(block, blocktext, lineno,
                                  targetmatch.group('name'))
        return [target], blank_finish

    def make_target(self, block, block_text, lineno, target_name):
        target_type, data = self.parse_target(block, block_text, lineno)
        if target_type == 'refname':
            target = nodes.target(block_text, '', refname=normalize_name(data))
            self.add_target(target_name, '', target, lineno)
            self.document.note_indirect_target(target)
            return target
        elif target_type == 'refuri':
            target = nodes.target(block_text, '')
            self.add_target(target_name, data, target, lineno)
            return target
        else:
            return data

    def parse_target(self, block, block_text, lineno):
        """
        Determine the type of reference of a target.

        :Return: A 2-tuple, one of:

            - 'refname' and the indirect reference name
            - 'refuri' and the URI
            - 'malformed' and a system_message node
        """
        if block and block[-1].strip()[-1:] == '_': # possible indirect target
            reference = ' '.join([line.strip() for line in block])
            refname = self.is_reference(reference)
            if refname:
                return 'refname', refname
        reference = ''.join([''.join(line.split()) for line in block])
        return 'refuri', unescape(reference)

    def is_reference(self, reference):
        match = self.explicit.patterns.reference.match(
            whitespace_normalize_name(reference))
        if not match:
            return None
        return unescape(match.group('simple') or match.group('phrase'))

    def add_target(self, targetname, refuri, target, lineno):
        target.line = lineno
        if targetname:
            name = normalize_name(unescape(targetname))
            target['names'].append(name)
            if refuri:
                uri = self.inliner.adjust_uri(refuri)
                if uri:
                    target['refuri'] = uri
                    self.document.note_external_target(target)
                else:
                    raise ApplicationError('problem with URI: %r' % refuri)
            else:
                self.document.note_internal_target(target)
            self.document.note_explicit_target(target, self.parent)
        else:                       # anonymous target
            if refuri:
                target['refuri'] = refuri
            else:
                self.document.note_internal_target(target)
            target['anonymous'] = 1
            self.document.note_anonymous_target(target)

    def substitution_def(self, match):
        pattern = self.explicit.patterns.substitution
        lineno = self.state_machine.abs_line_number()
        block, indent, offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end(),
                                                          strip_indent=0)
        blocktext = (match.string[:match.end()] + '\n'.join(block))
        block.disconnect()
        escaped = escape2null(block[0].rstrip())
        blockindex = 0
        while 1:
            subdefmatch = pattern.match(escaped)
            if subdefmatch:
                break
            blockindex += 1
            try:
                escaped = escaped + ' ' + escape2null(block[blockindex].strip())
            except IndexError:
                raise MarkupError('malformed substitution definition.',
                                  lineno)
        del block[:blockindex]          # strip out the substitution marker
        block[0] = (block[0].strip() + ' ')[subdefmatch.end()-len(escaped)-1:-1]
        if not block[0]:
            del block[0]
            offset += 1
        while block and not block[-1].strip():
            block.pop()
        subname = subdefmatch.group('name')
        substitution_node = nodes.substitution_definition(blocktext)
        substitution_node.line = lineno
        self.document.note_substitution_def(
            substitution_node,subname, self.parent)
        if block:
            block[0] = block[0].strip()
            new_abs_offset, blank_finish = self.nested_list_parse(
                  block, input_offset=offset, node=substitution_node,
                  initial_state='SubstitutionDef', blank_finish=blank_finish)
            i = 0
            for node in substitution_node[:]:
                if not (isinstance(node, nodes.Inline) or
                        isinstance(node, nodes.Text)):
                    self.parent += substitution_node[i]
                    del substitution_node[i]
                else:
                    i += 1
            if len(substitution_node) == 0:
                msg = self.reporter.warning(
                      'Substitution definition "%s" empty or invalid.'
                      % subname,
                      nodes.literal_block(blocktext, blocktext), line=lineno)
                return [msg], blank_finish
            else:
                return [substitution_node], blank_finish
        else:
            msg = self.reporter.warning(
                  'Substitution definition "%s" missing contents.' % subname,
                  nodes.literal_block(blocktext, blocktext), line=lineno)
            return [msg], blank_finish

    def directive(self, match, **option_presets):
        """Returns a 2-tuple: list of nodes, and a "blank finish" boolean."""
        type_name = match.group(1)
        directive_function, messages = directives.directive(
            type_name, self.memo.language, self.document)
        self.parent += messages
        if directive_function:
            return self.run_directive(
                directive_function, match, type_name, option_presets)
        else:
            return self.unknown_directive(type_name)

    def run_directive(self, directive_fn, match, type_name, option_presets):
        """
        Parse a directive then run its directive function.

        Parameters:

        - `directive_fn`: The function implementing the directive.  Uses
          function attributes ``arguments``, ``options``, and/or ``content``
          if present.

        - `match`: A regular expression match object which matched the first
          line of the directive.

        - `type_name`: The directive name, as used in the source text.

        - `option_presets`: A dictionary of preset options, defaults for the
          directive options.  Currently, only an "alt" option is passed by
          substitution definitions (value: the substitution name), which may
          be used by an embedded image directive.

        Returns a 2-tuple: list of nodes, and a "blank finish" boolean.
        """
        lineno = self.state_machine.abs_line_number()
        initial_line_offset = self.state_machine.line_offset
        indented, indent, line_offset, blank_finish \
                  = self.state_machine.get_first_known_indented(match.end(),
                                                                strip_top=0)
        block_text = '\n'.join(self.state_machine.input_lines[
            initial_line_offset : self.state_machine.line_offset + 1])
        try:
            arguments, options, content, content_offset = (
                self.parse_directive_block(indented, line_offset,
                                           directive_fn, option_presets))
        except MarkupError, detail:
            error = self.reporter.error(
                'Error in "%s" directive:\n%s.' % (type_name,
                                                   ' '.join(detail.args)),
                nodes.literal_block(block_text, block_text), line=lineno)
            return [error], blank_finish
        result = directive_fn(type_name, arguments, options, content, lineno,
                              content_offset, block_text, self,
                              self.state_machine)
        return (result,
                blank_finish or self.state_machine.is_next_line_blank())

    def parse_directive_block(self, indented, line_offset, directive_fn,
                              option_presets):
        arguments = []
        options = {}
        argument_spec = getattr(directive_fn, 'arguments', None)
        if argument_spec and argument_spec[:2] == (0, 0):
            argument_spec = None
        option_spec = getattr(directive_fn, 'options', None)
        content_spec = getattr(directive_fn, 'content', None)
        if indented and not indented[0].strip():
            indented.trim_start()
            line_offset += 1
        while indented and not indented[-1].strip():
            indented.trim_end()
        if indented and (argument_spec or option_spec):
            for i in range(len(indented)):
                if not indented[i].strip():
                    break
            else:
                i += 1
            arg_block = indented[:i]
            content = indented[i+1:]
            content_offset = line_offset + i + 1
        else:
            content = indented
            content_offset = line_offset
            arg_block = []
        while content and not content[0].strip():
            content.trim_start()
            content_offset += 1
        if option_spec:
            options, arg_block = self.parse_directive_options(
                option_presets, option_spec, arg_block)
            if arg_block and not argument_spec:
                raise MarkupError('no arguments permitted; blank line '
                                  'required before content block')
        if argument_spec:
            arguments = self.parse_directive_arguments(
                argument_spec, arg_block)
        if content and not content_spec:
            raise MarkupError('no content permitted')
        return (arguments, options, content, content_offset)

    def parse_directive_options(self, option_presets, option_spec, arg_block):
        options = option_presets.copy()
        for i in range(len(arg_block)):
            if arg_block[i][:1] == ':':
                opt_block = arg_block[i:]
                arg_block = arg_block[:i]
                break
        else:
            opt_block = []
        if opt_block:
            success, data = self.parse_extension_options(option_spec,
                                                         opt_block)
            if success:                 # data is a dict of options
                options.update(data)
            else:                       # data is an error string
                raise MarkupError(data)
        return options, arg_block

    def parse_directive_arguments(self, argument_spec, arg_block):
        required, optional, last_whitespace = argument_spec
        arg_text = '\n'.join(arg_block)
        arguments = arg_text.split()
        if len(arguments) < required:
            raise MarkupError('%s argument(s) required, %s supplied'
                              % (required, len(arguments)))
        elif len(arguments) > required + optional:
            if last_whitespace:
                arguments = arg_text.split(None, required + optional - 1)
            else:
                raise MarkupError(
                    'maximum %s argument(s) allowed, %s supplied'
                    % (required + optional, len(arguments)))
        return arguments

    def parse_extension_options(self, option_spec, datalines):
        """
        Parse `datalines` for a field list containing extension options
        matching `option_spec`.

        :Parameters:
            - `option_spec`: a mapping of option name to conversion
              function, which should raise an exception on bad input.
            - `datalines`: a list of input strings.

        :Return:
            - Success value, 1 or 0.
            - An option dictionary on success, an error string on failure.
        """
        node = nodes.field_list()
        newline_offset, blank_finish = self.nested_list_parse(
              datalines, 0, node, initial_state='ExtensionOptions',
              blank_finish=1)
        if newline_offset != len(datalines): # incomplete parse of block
            return 0, 'invalid option block'
        try:
            options = utils.extract_extension_options(node, option_spec)
        except KeyError, detail:
            return 0, ('unknown option: "%s"' % detail.args[0])
        except (ValueError, TypeError), detail:
            return 0, ('invalid option value: %s' % ' '.join(detail.args))
        except utils.ExtensionOptionError, detail:
            return 0, ('invalid option data: %s' % ' '.join(detail.args))
        if blank_finish:
            return 1, options
        else:
            return 0, 'option data incompletely parsed'

    def unknown_directive(self, type_name):
        lineno = self.state_machine.abs_line_number()
        indented, indent, offset, blank_finish = \
              self.state_machine.get_first_known_indented(0, strip_indent=0)
        text = '\n'.join(indented)
        error = self.reporter.error(
              'Unknown directive type "%s".' % type_name,
              nodes.literal_block(text, text), line=lineno)
        return [error], blank_finish

    def comment(self, match):
        if not match.string[match.end():].strip() \
              and self.state_machine.is_next_line_blank(): # an empty comment?
            return [nodes.comment()], 1 # "A tiny but practical wart."
        indented, indent, offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end())
        while indented and not indented[-1].strip():
            indented.trim_end()
        text = '\n'.join(indented)
        return [nodes.comment(text, text)], blank_finish

    explicit.constructs = [
          (footnote,
           re.compile(r"""
                      \.\.[ ]+          # explicit markup start
                      \[
                      (                 # footnote label:
                          [0-9]+          # manually numbered footnote
                        |               # *OR*
                          \#              # anonymous auto-numbered footnote
                        |               # *OR*
                          \#%s            # auto-number ed?) footnote label
                        |               # *OR*
                          \*              # auto-symbol footnote
                      )
                      \]
                      ([ ]+|$)          # whitespace or end of line
                      """ % Inliner.simplename, re.VERBOSE | re.UNICODE)),
          (citation,
           re.compile(r"""
                      \.\.[ ]+          # explicit markup start
                      \[(%s)\]          # citation label
                      ([ ]+|$)          # whitespace or end of line
                      """ % Inliner.simplename, re.VERBOSE | re.UNICODE)),
          (hyperlink_target,
           re.compile(r"""
                      \.\.[ ]+          # explicit markup start
                      _                 # target indicator
                      (?![ ]|$)         # first char. not space or EOL
                      """, re.VERBOSE)),
          (substitution_def,
           re.compile(r"""
                      \.\.[ ]+          # explicit markup start
                      \|                # substitution indicator
                      (?![ ]|$)         # first char. not space or EOL
                      """, re.VERBOSE)),
          (directive,
           re.compile(r"""
                      \.\.[ ]+          # explicit markup start
                      (%s)              # directive name
                      [ ]?              # optional space
                      ::                # directive delimiter
                      ([ ]+|$)          # whitespace or end of line
                      """ % Inliner.simplename, re.VERBOSE | re.UNICODE))]

    def explicit_markup(self, match, context, next_state):
        """Footnotes, hyperlink targets, directives, comments."""
        nodelist, blank_finish = self.explicit_construct(match)
        self.parent += nodelist
        self.explicit_list(blank_finish)
        return [], next_state, []

    def explicit_construct(self, match):
        """Determine which explicit construct this is, parse & return it."""
        errors = []
        for method, pattern in self.explicit.constructs:
            expmatch = pattern.match(match.string)
            if expmatch:
                try:
                    return method(self, expmatch)
                except MarkupError, (message, lineno): # never reached?
                    errors.append(self.reporter.warning(message, line=lineno))
                    break
        nodelist, blank_finish = self.comment(match)
        return nodelist + errors, blank_finish

    def explicit_list(self, blank_finish):
        """
        Create a nested state machine for a series of explicit markup
        constructs (including anonymous hyperlink targets).
        """
        offset = self.state_machine.line_offset + 1   # next line
        newline_offset, blank_finish = self.nested_list_parse(
              self.state_machine.input_lines[offset:],
              input_offset=self.state_machine.abs_line_offset() + 1,
              node=self.parent, initial_state='Explicit',
              blank_finish=blank_finish,
              match_titles=self.state_machine.match_titles)
        self.goto_line(newline_offset)
        if not blank_finish:
            self.parent += self.unindent_warning('Explicit markup')

    def anonymous(self, match, context, next_state):
        """Anonymous hyperlink targets."""
        nodelist, blank_finish = self.anonymous_target(match)
        self.parent += nodelist
        self.explicit_list(blank_finish)
        return [], next_state, []

    def anonymous_target(self, match):
        lineno = self.state_machine.abs_line_number()
        block, indent, offset, blank_finish \
              = self.state_machine.get_first_known_indented(match.end(),
                                                            until_blank=1)
        blocktext = match.string[:match.end()] + '\n'.join(block)
        block = [escape2null(line) for line in block]
        target = self.make_target(block, blocktext, lineno, '')
        return [target], blank_finish

    def line(self, match, context, next_state):
        """Section title overline or transition marker."""
        if self.state_machine.match_titles:
            return [match.string], 'Line', []
        elif match.string.strip() == '::':
            raise statemachine.TransitionCorrection('text')
        elif len(match.string.strip()) < 4:
            msg = self.reporter.info(
                'Unexpected possible title overline or transition.\n'
                "Treating it as ordinary text because it's so short.",
                line=self.state_machine.abs_line_number())
            self.parent += msg
            raise statemachine.TransitionCorrection('text')
        else:
            blocktext = self.state_machine.line
            msg = self.reporter.severe(
                  'Unexpected section title or transition.',
                  nodes.literal_block(blocktext, blocktext),
                  line=self.state_machine.abs_line_number())
            self.parent += msg
            return [], next_state, []

    def text(self, match, context, next_state):
        """Titles, definition lists, paragraphs."""
        return [match.string], 'Text', []


class RFC2822Body(Body):

    """
    RFC2822 headers are only valid as the first constructs in documents.  As
    soon as anything else appears, the `Body` state should take over.
    """

    patterns = Body.patterns.copy()     # can't modify the original
    patterns['rfc2822'] = r'[!-9;-~]+:( +|$)'
    initial_transitions = [(name, 'Body')
                           for name in Body.initial_transitions]
    initial_transitions.insert(-1, ('rfc2822', 'Body')) # just before 'text'

    def rfc2822(self, match, context, next_state):
        """RFC2822-style field list item."""
        fieldlist = nodes.field_list(classes=['rfc2822'])
        self.parent += fieldlist
        field, blank_finish = self.rfc2822_field(match)
        fieldlist += field
        offset = self.state_machine.line_offset + 1   # next line
        newline_offset, blank_finish = self.nested_list_parse(
              self.state_machine.input_lines[offset:],
              input_offset=self.state_machine.abs_line_offset() + 1,
              node=fieldlist, initial_state='RFC2822List',
              blank_finish=blank_finish)
        self.goto_line(newline_offset)
        if not blank_finish:
            self.parent += self.unindent_warning(
                  'RFC2822-style field list')
        return [], next_state, []

    def rfc2822_field(self, match):
        name = match.string[:match.string.find(':')]
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end(),
                                                          until_blank=1)
        fieldnode = nodes.field()
        fieldnode += nodes.field_name(name, name)
        fieldbody = nodes.field_body('\n'.join(indented))
        fieldnode += fieldbody
        if indented:
            self.nested_parse(indented, input_offset=line_offset,
                              node=fieldbody)
        return fieldnode, blank_finish


class SpecializedBody(Body):

    """
    Superclass for second and subsequent compound element members.  Compound
    elements are lists and list-like constructs.

    All transition methods are disabled (redefined as `invalid_input`).
    Override individual methods in subclasses to re-enable.

    For example, once an initial bullet list item, say, is recognized, the
    `BulletList` subclass takes over, with a "bullet_list" node as its
    container.  Upon encountering the initial bullet list item, `Body.bullet`
    calls its ``self.nested_list_parse`` (`RSTState.nested_list_parse`), which
    starts up a nested parsing session with `BulletList` as the initial state.
    Only the ``bullet`` transition method is enabled in `BulletList`; as long
    as only bullet list items are encountered, they are parsed and inserted
    into the container.  The first construct which is *not* a bullet list item
    triggers the `invalid_input` method, which ends the nested parse and
    closes the container.  `BulletList` needs to recognize input that is
    invalid in the context of a bullet list, which means everything *other
    than* bullet list items, so it inherits the transition list created in
    `Body`.
    """

    def invalid_input(self, match=None, context=None, next_state=None):
        """Not a compound element member. Abort this state machine."""
        self.state_machine.previous_line() # back up so parent SM can reassess
        raise EOFError

    indent = invalid_input
    bullet = invalid_input
    enumerator = invalid_input
    field_marker = invalid_input
    option_marker = invalid_input
    doctest = invalid_input
    line_block = invalid_input
    grid_table_top = invalid_input
    simple_table_top = invalid_input
    explicit_markup = invalid_input
    anonymous = invalid_input
    line = invalid_input
    text = invalid_input


class BulletList(SpecializedBody):

    """Second and subsequent bullet_list list_items."""

    def bullet(self, match, context, next_state):
        """Bullet list item."""
        if match.string[0] != self.parent['bullet']:
            # different bullet: new list
            self.invalid_input()
        listitem, blank_finish = self.list_item(match.end())
        self.parent += listitem
        self.blank_finish = blank_finish
        return [], next_state, []


class DefinitionList(SpecializedBody):

    """Second and subsequent definition_list_items."""

    def text(self, match, context, next_state):
        """Definition lists."""
        return [match.string], 'Definition', []


class EnumeratedList(SpecializedBody):

    """Second and subsequent enumerated_list list_items."""

    def enumerator(self, match, context, next_state):
        """Enumerated list item."""
        format, sequence, text, ordinal = self.parse_enumerator(
              match, self.parent['enumtype'])
        if ( format != self.format
             or (sequence != '#' and (sequence != self.parent['enumtype']
                                      or self.auto
                                      or ordinal != (self.lastordinal + 1)))
             or not self.is_enumerated_list_item(ordinal, sequence, format)):
            # different enumeration: new list
            self.invalid_input()
        if sequence == '#':
            self.auto = 1
        listitem, blank_finish = self.list_item(match.end())
        self.parent += listitem
        self.blank_finish = blank_finish
        self.lastordinal = ordinal
        return [], next_state, []


class FieldList(SpecializedBody):

    """Second and subsequent field_list fields."""

    def field_marker(self, match, context, next_state):
        """Field list field."""
        field, blank_finish = self.field(match)
        self.parent += field
        self.blank_finish = blank_finish
        return [], next_state, []


class OptionList(SpecializedBody):

    """Second and subsequent option_list option_list_items."""

    def option_marker(self, match, context, next_state):
        """Option list item."""
        try:
            option_list_item, blank_finish = self.option_list_item(match)
        except MarkupError, (message, lineno):
            self.invalid_input()
        self.parent += option_list_item
        self.blank_finish = blank_finish
        return [], next_state, []


class RFC2822List(SpecializedBody, RFC2822Body):

    """Second and subsequent RFC2822-style field_list fields."""

    patterns = RFC2822Body.patterns
    initial_transitions = RFC2822Body.initial_transitions

    def rfc2822(self, match, context, next_state):
        """RFC2822-style field list item."""
        field, blank_finish = self.rfc2822_field(match)
        self.parent += field
        self.blank_finish = blank_finish
        return [], 'RFC2822List', []

    blank = SpecializedBody.invalid_input


class ExtensionOptions(FieldList):

    """
    Parse field_list fields for extension options.

    No nested parsing is done (including inline markup parsing).
    """

    def parse_field_body(self, indented, offset, node):
        """Override `Body.parse_field_body` for simpler parsing."""
        lines = []
        for line in list(indented) + ['']:
            if line.strip():
                lines.append(line)
            elif lines:
                text = '\n'.join(lines)
                node += nodes.paragraph(text, text)
                lines = []


class LineBlock(SpecializedBody):

    """Second and subsequent lines of a line_block."""

    blank = SpecializedBody.invalid_input

    def line_block(self, match, context, next_state):
        """New line of line block."""
        lineno = self.state_machine.abs_line_number()
        line, messages, blank_finish = self.line_block_line(match, lineno)
        self.parent += line
        self.parent.parent += messages
        self.blank_finish = blank_finish
        return [], next_state, []


class Explicit(SpecializedBody):

    """Second and subsequent explicit markup construct."""

    def explicit_markup(self, match, context, next_state):
        """Footnotes, hyperlink targets, directives, comments."""
        nodelist, blank_finish = self.explicit_construct(match)
        self.parent += nodelist
        self.blank_finish = blank_finish
        return [], next_state, []

    def anonymous(self, match, context, next_state):
        """Anonymous hyperlink targets."""
        nodelist, blank_finish = self.anonymous_target(match)
        self.parent += nodelist
        self.blank_finish = blank_finish
        return [], next_state, []

    blank = SpecializedBody.invalid_input


class SubstitutionDef(Body):

    """
    Parser for the contents of a substitution_definition element.
    """

    patterns = {
          'embedded_directive': re.compile(r'(%s)::( +|$)'
                                           % Inliner.simplename, re.UNICODE),
          'text': r''}
    initial_transitions = ['embedded_directive', 'text']

    def embedded_directive(self, match, context, next_state):
        nodelist, blank_finish = self.directive(match,
                                                alt=self.parent['names'][0])
        self.parent += nodelist
        if not self.state_machine.at_eof():
            self.blank_finish = blank_finish
        raise EOFError

    def text(self, match, context, next_state):
        if not self.state_machine.at_eof():
            self.blank_finish = self.state_machine.is_next_line_blank()
        raise EOFError


class Text(RSTState):

    """
    Classifier of second line of a text block.

    Could be a paragraph, a definition list item, or a title.
    """

    patterns = {'underline': Body.patterns['line'],
                'text': r''}
    initial_transitions = [('underline', 'Body'), ('text', 'Body')]

    def blank(self, match, context, next_state):
        """End of paragraph."""
        paragraph, literalnext = self.paragraph(
              context, self.state_machine.abs_line_number() - 1)
        self.parent += paragraph
        if literalnext:
            self.parent += self.literal_block()
        return [], 'Body', []

    def eof(self, context):
        if context:
            self.blank(None, context, None)
        return []

    def indent(self, match, context, next_state):
        """Definition list item."""
        definitionlist = nodes.definition_list()
        definitionlistitem, blank_finish = self.definition_list_item(context)
        definitionlist += definitionlistitem
        self.parent += definitionlist
        offset = self.state_machine.line_offset + 1   # next line
        newline_offset, blank_finish = self.nested_list_parse(
              self.state_machine.input_lines[offset:],
              input_offset=self.state_machine.abs_line_offset() + 1,
              node=definitionlist, initial_state='DefinitionList',
              blank_finish=blank_finish, blank_finish_state='Definition')
        self.goto_line(newline_offset)
        if not blank_finish:
            self.parent += self.unindent_warning('Definition list')
        return [], 'Body', []

    def underline(self, match, context, next_state):
        """Section title."""
        lineno = self.state_machine.abs_line_number()
        title = context[0].rstrip()
        underline = match.string.rstrip()
        source = title + '\n' + underline
        messages = []
        if len(title) > len(underline):
            if len(underline) < 4:
                if self.state_machine.match_titles:
                    msg = self.reporter.info(
                        'Possible title underline, too short for the title.\n'
                        "Treating it as ordinary text because it's so short.",
                        line=lineno)
                    self.parent += msg
                raise statemachine.TransitionCorrection('text')
            else:
                blocktext = context[0] + '\n' + self.state_machine.line
                msg = self.reporter.warning(
                    'Title underline too short.',
                    nodes.literal_block(blocktext, blocktext), line=lineno)
                messages.append(msg)
        if not self.state_machine.match_titles:
            blocktext = context[0] + '\n' + self.state_machine.line
            msg = self.reporter.severe(
                'Unexpected section title.',
                nodes.literal_block(blocktext, blocktext), line=lineno)
            self.parent += messages
            self.parent += msg
            return [], next_state, []
        style = underline[0]
        context[:] = []
        self.section(title, source, style, lineno - 1, messages)
        return [], next_state, []

    def text(self, match, context, next_state):
        """Paragraph."""
        startline = self.state_machine.abs_line_number() - 1
        msg = None
        try:
            block = self.state_machine.get_text_block(flush_left=1)
        except statemachine.UnexpectedIndentationError, instance:
            block, source, lineno = instance.args
            msg = self.reporter.error('Unexpected indentation.',
                                      source=source, line=lineno)
        lines = context + list(block)
        paragraph, literalnext = self.paragraph(lines, startline)
        self.parent += paragraph
        self.parent += msg
        if literalnext:
            try:
                self.state_machine.next_line()
            except EOFError:
                pass
            self.parent += self.literal_block()
        return [], next_state, []

    def literal_block(self):
        """Return a list of nodes."""
        indented, indent, offset, blank_finish = \
              self.state_machine.get_indented()
        while indented and not indented[-1].strip():
            indented.trim_end()
        if not indented:
            return self.quoted_literal_block()
        data = '\n'.join(indented)
        literal_block = nodes.literal_block(data, data)
        literal_block.line = offset + 1
        nodelist = [literal_block]
        if not blank_finish:
            nodelist.append(self.unindent_warning('Literal block'))
        return nodelist

    def quoted_literal_block(self):
        abs_line_offset = self.state_machine.abs_line_offset()
        offset = self.state_machine.line_offset
        parent_node = nodes.Element()
        new_abs_offset = self.nested_parse(
            self.state_machine.input_lines[offset:],
            input_offset=abs_line_offset, node=parent_node, match_titles=0,
            state_machine_kwargs={'state_classes': (QuotedLiteralBlock,),
                                  'initial_state': 'QuotedLiteralBlock'})
        self.goto_line(new_abs_offset)
        return parent_node.children

    def definition_list_item(self, termline):
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_indented()
        definitionlistitem = nodes.definition_list_item(
            '\n'.join(termline + list(indented)))
        lineno = self.state_machine.abs_line_number() - 1
        definitionlistitem.line = lineno
        termlist, messages = self.term(termline, lineno)
        definitionlistitem += termlist
        definition = nodes.definition('', *messages)
        definitionlistitem += definition
        if termline[0][-2:] == '::':
            definition += self.reporter.info(
                  'Blank line missing before literal block (after the "::")? '
                  'Interpreted as a definition list item.', line=line_offset+1)
        self.nested_parse(indented, input_offset=line_offset, node=definition)
        return definitionlistitem, blank_finish

    classifier_delimiter = re.compile(' +: +')

    def term(self, lines, lineno):
        """Return a definition_list's term and optional classifiers."""
        assert len(lines) == 1
        text_nodes, messages = self.inline_text(lines[0], lineno)
        term_node = nodes.term()
        node_list = [term_node]
        for i in range(len(text_nodes)):
            node = text_nodes[i]
            if isinstance(node, nodes.Text):
                parts = self.classifier_delimiter.split(node.rawsource)
                if len(parts) == 1:
                    node_list[-1] += node
                else:
                    
                    node_list[-1] += nodes.Text(parts[0].rstrip())
                    for part in parts[1:]:
                        classifier_node = nodes.classifier('', part)
                        node_list.append(classifier_node)
            else:
                node_list[-1] += node
        return node_list, messages


class SpecializedText(Text):

    """
    Superclass for second and subsequent lines of Text-variants.

    All transition methods are disabled. Override individual methods in
    subclasses to re-enable.
    """

    def eof(self, context):
        """Incomplete construct."""
        return []

    def invalid_input(self, match=None, context=None, next_state=None):
        """Not a compound element member. Abort this state machine."""
        raise EOFError

    blank = invalid_input
    indent = invalid_input
    underline = invalid_input
    text = invalid_input


class Definition(SpecializedText):

    """Second line of potential definition_list_item."""

    def eof(self, context):
        """Not a definition."""
        self.state_machine.previous_line(2) # so parent SM can reassess
        return []

    def indent(self, match, context, next_state):
        """Definition list item."""
        definitionlistitem, blank_finish = self.definition_list_item(context)
        self.parent += definitionlistitem
        self.blank_finish = blank_finish
        return [], 'DefinitionList', []


class Line(SpecializedText):

    """
    Second line of over- & underlined section title or transition marker.
    """

    eofcheck = 1                        # @@@ ???
    """Set to 0 while parsing sections, so that we don't catch the EOF."""

    def eof(self, context):
        """Transition marker at end of section or document."""
        marker = context[0].strip()
        if self.memo.section_bubble_up_kludge:
            self.memo.section_bubble_up_kludge = 0
        elif len(marker) < 4:
            self.state_correction(context)
        if self.eofcheck:               # ignore EOFError with sections
            lineno = self.state_machine.abs_line_number() - 1
            transition = nodes.transition(rawsource=context[0])
            transition.line = lineno
            self.parent += transition
        self.eofcheck = 1
        return []

    def blank(self, match, context, next_state):
        """Transition marker."""
        lineno = self.state_machine.abs_line_number() - 1
        marker = context[0].strip()
        if len(marker) < 4:
            self.state_correction(context)
        transition = nodes.transition(rawsource=marker)
        transition.line = lineno
        self.parent += transition
        return [], 'Body', []

    def text(self, match, context, next_state):
        """Potential over- & underlined title."""
        lineno = self.state_machine.abs_line_number() - 1
        overline = context[0]
        title = match.string
        underline = ''
        try:
            underline = self.state_machine.next_line()
        except EOFError:
            blocktext = overline + '\n' + title
            if len(overline.rstrip()) < 4:
                self.short_overline(context, blocktext, lineno, 2)
            else:
                msg = self.reporter.severe(
                    'Incomplete section title.',
                    nodes.literal_block(blocktext, blocktext), line=lineno)
                self.parent += msg
                return [], 'Body', []
        source = '%s\n%s\n%s' % (overline, title, underline)
        overline = overline.rstrip()
        underline = underline.rstrip()
        if not self.transitions['underline'][0].match(underline):
            blocktext = overline + '\n' + title + '\n' + underline
            if len(overline.rstrip()) < 4:
                self.short_overline(context, blocktext, lineno, 2)
            else:
                msg = self.reporter.severe(
                    'Missing matching underline for section title overline.',
                    nodes.literal_block(source, source), line=lineno)
                self.parent += msg
                return [], 'Body', []
        elif overline != underline:
            blocktext = overline + '\n' + title + '\n' + underline
            if len(overline.rstrip()) < 4:
                self.short_overline(context, blocktext, lineno, 2)
            else:
                msg = self.reporter.severe(
                      'Title overline & underline mismatch.',
                      nodes.literal_block(source, source), line=lineno)
                self.parent += msg
                return [], 'Body', []
        title = title.rstrip()
        messages = []
        if len(title) > len(overline):
            blocktext = overline + '\n' + title + '\n' + underline
            if len(overline.rstrip()) < 4:
                self.short_overline(context, blocktext, lineno, 2)
            else:
                msg = self.reporter.warning(
                      'Title overline too short.',
                      nodes.literal_block(source, source), line=lineno)
                messages.append(msg)
        style = (overline[0], underline[0])
        self.eofcheck = 0               # @@@ not sure this is correct
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        self.eofcheck = 1
        return [], 'Body', []

    indent = text                       # indented title

    def underline(self, match, context, next_state):
        overline = context[0]
        blocktext = overline + '\n' + self.state_machine.line
        lineno = self.state_machine.abs_line_number() - 1
        if len(overline.rstrip()) < 4:
            self.short_overline(context, blocktext, lineno, 1)
        msg = self.reporter.error(
              'Invalid section title or transition marker.',
              nodes.literal_block(blocktext, blocktext), line=lineno)
        self.parent += msg
        return [], 'Body', []

    def short_overline(self, context, blocktext, lineno, lines=1):
        msg = self.reporter.info(
            'Possible incomplete section title.\nTreating the overline as '
            "ordinary text because it's so short.", line=lineno)
        self.parent += msg
        self.state_correction(context, lines)

    def state_correction(self, context, lines=1):
        self.state_machine.previous_line(lines)
        context[:] = []
        raise statemachine.StateCorrection('Body', 'text')


class QuotedLiteralBlock(RSTState):

    """
    Nested parse handler for quoted (unindented) literal blocks.

    Special-purpose.  Not for inclusion in `state_classes`.
    """

    patterns = {'initial_quoted': r'(%(nonalphanum7bit)s)' % Body.pats,
                'text': r''}
    initial_transitions = ('initial_quoted', 'text')

    def __init__(self, state_machine, debug=0):
        RSTState.__init__(self, state_machine, debug)
        self.messages = []
        self.initial_lineno = None

    def blank(self, match, context, next_state):
        if context:
            raise EOFError
        else:
            return context, next_state, []

    def eof(self, context):
        if context:
            text = '\n'.join(context)
            literal_block = nodes.literal_block(text, text)
            literal_block.line = self.initial_lineno
            self.parent += literal_block
        else:
            self.parent += self.reporter.warning(
                'Literal block expected; none found.',
                line=self.state_machine.abs_line_number())
            self.state_machine.previous_line()
        self.parent += self.messages
        return []

    def indent(self, match, context, next_state):
        assert context, ('QuotedLiteralBlock.indent: context should not '
                         'be empty!')
        self.messages.append(
            self.reporter.error('Unexpected indentation.',
                                line=self.state_machine.abs_line_number()))
        self.state_machine.previous_line()
        raise EOFError

    def initial_quoted(self, match, context, next_state):
        """Match arbitrary quote character on the first line only."""
        self.remove_transition('initial_quoted')
        quote = match.string[0]
        pattern = re.compile(re.escape(quote))
        # New transition matches consistent quotes only:
        self.add_transition('quoted',
                            (pattern, self.quoted, self.__class__.__name__))
        self.initial_lineno = self.state_machine.abs_line_number()
        return [match.string], next_state, []

    def quoted(self, match, context, next_state):
        """Match consistent quotes on subsequent lines."""
        context.append(match.string)
        return context, next_state, []

    def text(self, match, context, next_state):
        if context:
            self.messages.append(
                self.reporter.error('Inconsistent literal block quoting.',
                                    line=self.state_machine.abs_line_number()))
            self.state_machine.previous_line()
        raise EOFError


state_classes = (Body, BulletList, DefinitionList, EnumeratedList, FieldList,
                 OptionList, LineBlock, ExtensionOptions, Explicit, Text,
                 Definition, Line, SubstitutionDef, RFC2822Body, RFC2822List)
"""Standard set of State classes used to start `RSTStateMachine`."""
���Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/rst/roles.py�������������������������������������0000644�0001750�0001750�00000031333�10322224711�024571� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: Edward Loper
# Contact: edloper@gradient.cis.upenn.edu
# Revision: $Revision: 3155 $
# Date: $Date: 2005-04-02 23:57:06 +0200 (Sat, 02 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
This module defines standard interpreted text role functions, a registry for
interpreted text roles, and an API for adding to and retrieving from the
registry.

The interface for interpreted role functions is as follows::

    def role_fn(name, rawtext, text, lineno, inliner,
                options={}, content=[]):
        code...

    # Set function attributes for customization:
    role_fn.options = ...
    role_fn.content = ...

Parameters:

- ``name`` is the local name of the interpreted text role, the role name
  actually used in the document.

- ``rawtext`` is a string containing the entire interpreted text construct.
  Return it as a ``problematic`` node linked to a system message if there is a
  problem.

- ``text`` is the interpreted text content, with backslash escapes converted
  to nulls (``\x00``).

- ``lineno`` is the line number where the interpreted text beings.

- ``inliner`` is the Inliner object that called the role function.
  It defines the following useful attributes: ``reporter``,
  ``problematic``, ``memo``, ``parent``, ``document``.

- ``options``: A dictionary of directive options for customization, to be
  interpreted by the role function.  Used for additional attributes for the
  generated elements and other functionality.

- ``content``: A list of strings, the directive content for customization
  ("role" directive).  To be interpreted by the role function.

Function attributes for customization, interpreted by the "role" directive:

- ``options``: A dictionary, mapping known option names to conversion
  functions such as `int` or `float`.  ``None`` or an empty dict implies no
  options to parse.  Several directive option conversion functions are defined
  in the `directives` module.

  All role functions implicitly support the "class" option, unless disabled
  with an explicit ``{'class': None}``.

- ``content``: A boolean; true if content is allowed.  Client code must handle
  the case where content is required but not supplied (an empty content list
  will be supplied).

Note that unlike directives, the "arguments" function attribute is not
supported for role customization.  Directive arguments are handled by the
"role" directive itself.

Interpreted role functions return a tuple of two values:

- A list of nodes which will be inserted into the document tree at the
  point where the interpreted role was encountered (can be an empty
  list).

- A list of system messages, which will be inserted into the document tree
  immediately after the end of the current inline block (can also be empty).
"""

__docformat__ = 'reStructuredText'

from docutils import nodes, utils
from docutils.parsers.rst import directives
from docutils.parsers.rst.languages import en as _fallback_language_module

DEFAULT_INTERPRETED_ROLE = 'title-reference'
"""
The canonical name of the default interpreted role.  This role is used
when no role is specified for a piece of interpreted text.
"""

_role_registry = {}
"""Mapping of canonical role names to role functions.  Language-dependent role
names are defined in the ``language`` subpackage."""

_roles = {}
"""Mapping of local or language-dependent interpreted text role names to role
functions."""

def role(role_name, language_module, lineno, reporter):
    """
    Locate and return a role function from its language-dependent name, along
    with a list of system messages.  If the role is not found in the current
    language, check English.  Return a 2-tuple: role function (``None`` if the
    named role cannot be found) and a list of system messages.
    """
    normname = role_name.lower()
    messages = []
    msg_text = []

    if _roles.has_key(normname):
        return _roles[normname], messages

    if role_name:
        canonicalname = None
        try:
            canonicalname = language_module.roles[normname]
        except AttributeError, error:
            msg_text.append('Problem retrieving role entry from language '
                            'module %r: %s.' % (language_module, error))
        except KeyError:
            msg_text.append('No role entry for "%s" in module "%s".'
                            % (role_name, language_module.__name__))
    else:
        canonicalname = DEFAULT_INTERPRETED_ROLE

    # If we didn't find it, try English as a fallback.
    if not canonicalname:
        try:
            canonicalname = _fallback_language_module.roles[normname]
            msg_text.append('Using English fallback for role "%s".'
                            % role_name)
        except KeyError:
            msg_text.append('Trying "%s" as canonical role name.'
                            % role_name)
            # The canonical name should be an English name, but just in case:
            canonicalname = normname

    # Collect any messages that we generated.
    if msg_text:
        message = reporter.info('\n'.join(msg_text), line=lineno)
        messages.append(message)

    # Look the role up in the registry, and return it.
    if _role_registry.has_key(canonicalname):
        role_fn = _role_registry[canonicalname]
        register_local_role(normname, role_fn)
        return role_fn, messages
    else:
        return None, messages # Error message will be generated by caller.

def register_canonical_role(name, role_fn):
    """
    Register an interpreted text role by its canonical name.

    :Parameters:
      - `name`: The canonical name of the interpreted role.
      - `role_fn`: The role function.  See the module docstring.
    """
    set_implicit_options(role_fn)
    _role_registry[name] = role_fn

def register_local_role(name, role_fn):
    """
    Register an interpreted text role by its local or language-dependent name.

    :Parameters:
      - `name`: The local or language-dependent name of the interpreted role.
      - `role_fn`: The role function.  See the module docstring.
    """
    set_implicit_options(role_fn)
    _roles[name] = role_fn

def set_implicit_options(role_fn):
    """
    Add customization options to role functions, unless explicitly set or
    disabled.
    """
    if not hasattr(role_fn, 'options') or role_fn.options is None:
        role_fn.options = {'class': directives.class_option}
    elif not role_fn.options.has_key('class'):
        role_fn.options['class'] = directives.class_option

def register_generic_role(canonical_name, node_class):
    """For roles which simply wrap a given `node_class` around the text."""
    role = GenericRole(canonical_name, node_class)
    register_canonical_role(canonical_name, role)


class GenericRole:

    """
    Generic interpreted text role, where the interpreted text is simply
    wrapped with the provided node class.
    """

    def __init__(self, role_name, node_class):
        self.name = role_name
        self.node_class = node_class

    def __call__(self, role, rawtext, text, lineno, inliner,
                 options={}, content=[]):
        set_classes(options)
        return [self.node_class(rawtext, utils.unescape(text), **options)], []


class CustomRole:

    """
    Wrapper for custom interpreted text roles.
    """

    def __init__(self, role_name, base_role, options={}, content=[]):
        self.name = role_name
        self.base_role = base_role
        self.options = None
        if hasattr(base_role, 'options'):
            self.options = base_role.options
        self.content = None
        if hasattr(base_role, 'content'):
            self.content = base_role.content
        self.supplied_options = options
        self.supplied_content = content

    def __call__(self, role, rawtext, text, lineno, inliner,
                 options={}, content=[]):
        opts = self.supplied_options.copy()
        opts.update(options)
        cont = list(self.supplied_content)
        if cont and content:
            cont += '\n'
        cont.extend(content)
        return self.base_role(role, rawtext, text, lineno, inliner,
                              options=opts, content=cont)


def generic_custom_role(role, rawtext, text, lineno, inliner,
                        options={}, content=[]):
    """"""
    # Once nested inline markup is implemented, this and other methods should
    # recursively call inliner.nested_parse().
    set_classes(options)
    return [nodes.inline(rawtext, utils.unescape(text), **options)], []

generic_custom_role.options = {'class': directives.class_option}


######################################################################
# Define and register the standard roles:
######################################################################

register_generic_role('abbreviation', nodes.abbreviation)
register_generic_role('acronym', nodes.acronym)
register_generic_role('emphasis', nodes.emphasis)
register_generic_role('literal', nodes.literal)
register_generic_role('strong', nodes.strong)
register_generic_role('subscript', nodes.subscript)
register_generic_role('superscript', nodes.superscript)
register_generic_role('title-reference', nodes.title_reference)

def pep_reference_role(role, rawtext, text, lineno, inliner,
                       options={}, content=[]):
    try:
        pepnum = int(text)
        if pepnum < 0 or pepnum > 9999:
            raise ValueError
    except ValueError:
        msg = inliner.reporter.error(
            'PEP number must be a number from 0 to 9999; "%s" is invalid.'
            % text, line=lineno)
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    # Base URL mainly used by inliner.pep_reference; so this is correct:
    ref = inliner.document.settings.pep_base_url + inliner.pep_url % pepnum
    set_classes(options)
    return [nodes.reference(rawtext, 'PEP ' + utils.unescape(text), refuri=ref,
                            **options)], []

register_canonical_role('pep-reference', pep_reference_role)

def rfc_reference_role(role, rawtext, text, lineno, inliner,
                       options={}, content=[]):
    try:
        rfcnum = int(text)
        if rfcnum <= 0:
            raise ValueError
    except ValueError:
        msg = inliner.reporter.error(
            'RFC number must be a number greater than or equal to 1; '
            '"%s" is invalid.' % text, line=lineno)
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    # Base URL mainly used by inliner.rfc_reference, so this is correct:
    ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
    set_classes(options)
    node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref,
                           **options)
    return [node], []

register_canonical_role('rfc-reference', rfc_reference_role)

def raw_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
    if not options.has_key('format'):
        msg = inliner.reporter.error(
            'No format (Writer name) is associated with this role: "%s".\n'
            'The "raw" role cannot be used directly.\n'
            'Instead, use the "role" directive to create a new role with '
            'an associated format.' % role, line=lineno)
        prb = inliner.problematic(rawtext, rawtext, msg)
        return [prb], [msg]
    set_classes(options)
    node = nodes.raw(rawtext, utils.unescape(text, 1), **options)
    return [node], []

raw_role.options = {'format': directives.unchanged}

register_canonical_role('raw', raw_role)


######################################################################
# Register roles that are currently unimplemented.
######################################################################

def unimplemented_role(role, rawtext, text, lineno, inliner, attributes={}):
    msg = inliner.reporter.error(
        'Interpreted text role "%s" not implemented.' % role, line=lineno)
    prb = inliner.problematic(rawtext, rawtext, msg)
    return [prb], [msg]

register_canonical_role('index', unimplemented_role)
register_canonical_role('named-reference', unimplemented_role)
register_canonical_role('anonymous-reference', unimplemented_role)
register_canonical_role('uri-reference', unimplemented_role)
register_canonical_role('footnote-reference', unimplemented_role)
register_canonical_role('citation-reference', unimplemented_role)
register_canonical_role('substitution-reference', unimplemented_role)
register_canonical_role('target', unimplemented_role)

# This should remain unimplemented, for testing purposes:
register_canonical_role('restructuredtext-unimplemented-role',
                        unimplemented_role)


def set_classes(options):
    """
    Auxiliary function to set options['classes'] and delete
    options['class'].
    """
    if options.has_key('class'):
        assert not options.has_key('classes')
        options['classes'] = options['class']
        del options['class']
�����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/parsers/__init__.py��������������������������������������0000644�0001750�0001750�00000002761�10322224711�024377� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 1645 $
# Date: $Date: 2003-08-27 22:50:43 +0200 (Wed, 27 Aug 2003) $
# Copyright: This module has been placed in the public domain.

"""
This package contains Docutils parser modules.
"""

__docformat__ = 'reStructuredText'

from docutils import Component


class Parser(Component):

    component_type = 'parser'
    config_section = 'parsers'

    def parse(self, inputstring, document):
        """Override to parse `inputstring` into document tree `document`."""
        raise NotImplementedError('subclass must override this method')

    def setup_parse(self, inputstring, document):
        """Initial parse setup.  Call at start of `self.parse()`."""
        self.inputstring = inputstring
        self.document = document
        document.reporter.attach_observer(document.note_parse_message)

    def finish_parse(self):
        """Finalize parse details.  Call at end of `self.parse()`."""
        self.document.reporter.detach_observer(
            self.document.note_parse_message)


_parser_aliases = {
      'restructuredtext': 'rst',
      'rest': 'rst',
      'restx': 'rst',
      'rtxt': 'rst',}

def get_parser_class(parser_name):
    """Return the Parser class from the `parser_name` module."""
    parser_name = parser_name.lower()
    if _parser_aliases.has_key(parser_name):
        parser_name = _parser_aliases[parser_name]
    module = __import__(parser_name, globals(), locals())
    return module.Parser
���������������Zope-2.9.4-retire_zpkg/lib/python/docutils/HISTORY.txt����������������������������������������������0000644�0001750�0001750�00000176242�10172235404�022523� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������==================
 Docutils History
==================

:Author: David Goodger; open to all Docutils developers
:Contact: goodger@python.org
:Date: $Date: 2005/01/07 15:11:43 $
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.

.. contents::


Release 0.3.7 (2004-12-24)
==========================

* docutils/frontend.py:

  - Added options: --input-encoding-error-handler,
    --record-dependencies, --leave-footnote-reference-space,
    --strict-visitor.
  - Added command-line and config file support for "overrides" setting
    parameter.

* docutils/io.py:

  - Added support for input encoding error handler.

* docutils/nodes.py:

  - Added dispatch_visit and dispatch_departure methods to
    NodeVisitor; useful as a hook for Visitors.
  - Changed structure of ``line_block``; added ``line``.
  - Added ``compound`` node class.
  - Added a mechanism for Visitors to transitionally ignore new node
    classes.

* docutils/utils.py:

  - Moved ``escape2null`` and ``unescape`` functions from
    docutils/parsers/rst/states.py.

* docutils/parsers/rst/roles.py:

  - Added "raw" role.
  - Changed role function API: the "text" parameter now takes
    null-escaped interpreted text content.

* docutils/parsers/rst/states.py:

  - Fixed bug where a "role" directive in a nested parse would crash
    the parser; the state machine's "language" attribute was not being
    copied over.
  - Added support for line block syntax.
  - Fixed directive parsing bug: argument-less directives didn't
    notice that arguments were present.
  - Removed error checking for transitions.
  - Added support for multiple classifiers in definition list items.
  - Moved ``escape2null`` and ``unescape`` functions to docutils/utils.py.
  - Changed role function API: the "text" parameter now takes
    null-escaped interpreted text content.
  - Empty sections and documents are allowed now.

* docutils/parsers/rst/directives/__init__.py:

  - Added ``encoding`` directive option conversion function.
  - Allow multiple class names in class_option conversion function.

* docutils/parsers/rst/directives/body.py:

  - Converted the line-block directive to use the new structure.
  - Extracted the old line-block functionality to the ``block``
    function (still used).
  - Added ``compound`` directive (thanks to Felix Wiemann).

* docutils/parsers/rst/directives/misc.py:

  - Added "encoding" option to "include" and "raw" directives.
  - Added "trim", "ltrim", and "rtrim" options to "unicode" directive.
  - Allow multiple class names in the "class" directive.

* docutils/parsers/rst/directives/parts.py:

  - Directive "sectnum" now accepts "prefix", "suffix", and "start"
    options.  Thanks to Lele Gaifax.

* docutils/parsers/rst/directives/tables.py:

  - Added "encoding" directive to "csv-table" directive.
  - Added workaround for lack of Unicode support in csv.py, for
    non-ASCII CSV input.

* docutils/transforms/misc.py:

  - Fixed bug when multiple "class" directives are applied to a single
    element.
  - Enabled multiple format names for "raw" directive.

* docutils/transforms/references.py:

  - Added support for trimming whitespace from beside substitution
    references.

* docutils/transforms/universal.py:

  - FinalChecks now checks for illegal transitions and moves
    transitions between sections.

* docutils/writers/html4css1.py:

  - HTMLTranslator.encode now converts U+00A0 to " ".
  - "stylesheet" and "stylesheet_path" settings are now mutually
    exclusive.
  - Added support for the new line_block/line structure.
  - --footnote-references now overrides
    --trim-footnote-reference-space, if applicable.
  - Added support for ``compound`` elements.
  - Enabled multiple format names for "raw" directive.
  - ``<p>`` tags of a paragraph which is the only visible child of the
    document node are no longer stripped.
  - Moved paragraph-compacting logic (for stripping ``<p>`` tags) to
    new method ``should_be_compact_paragraph()``.
  - Added class="docutils" to ``dl``, ``hr``, ``table`` and ``tt``
    elements.
  - "raw" elements are now surrounded by ``span`` or ``div`` tags in
    the output if they have their ``class`` attribute set.
  - The whole document is now surrounded by a ``<div
    class="document">`` element.
  - Body-level images are now wrapped by their own ``<div>`` elements,
    with image classes copied to the wrapper, and for images which
    have the ``:align:`` option set, the surrounding ``<div>`` now
    receives a class attribute (like ``class="align-left"``).

* docutils/writers/latex2e.py:

  - no newline after depart_term.
  - Added translations for some Unicode quotes.
  - Added option "font-encoding", made package AE the default.
  - "stylesheet" and "stylesheet_path" settings are now mutually
    exclusive.
  - --footnote-references now overrides
    --trim-footnote-reference-space, if applicable.
  - The footnote label style now matches the footnote reference style
    ("brackets" or "superscript").
  - Added support for ``compound`` elements.
  - Enabled multiple format names for "raw" directive.

* docs/ref/docutils.dtd:

  - Changed structure of the ``line_block`` element; added ``line``.
  - Added ``compound`` element.
  - Added "ltrim" and "rtrim" attributes to
    ``substitution_definition`` element.
  - Enabled multiple format names for ``raw`` element.
  - Enabled multiple classifiers in ``definition_list_item`` elements.

* docs/ref/rst/directives.txt

  - Marked "line-block" as deprecated.
  - "Class" directive now allows multiple class names.
  - Added "Rationale for Class Attribute Value Conversion".
  - Added warning about "raw" overuse/abuse.

* docs/ref/rst/restructuredtext.txt:

  - Added syntax for line blocks.
  - Definition list items may have multiple classifiers.

* docs/ref/rst/roles.txt:

  - Added "raw" role.

* tools/stylesheets/default.css:

  - Added support for the new line_block structure.
  - Added "docutils" class to ``dl``, ``hr``, ``table`` and ``tt``.


Release 0.3.5 (2004-07-29)
==========================

General:

* _`Documentation cleanup/reorganization`.

  - Created new subdirectories of docs/:

    * ``docs/user/``: introductory/tutorial material for end-users
    * ``docs/dev/``: for core-developers (development notes, plans, etc.)
    * ``docs/api/``: API reference material for client-developers
    * ``docs/ref/``: reference material for all groups
    * ``docs/howto/``: for component-developers and core-developers
    * ``docs/peps/``: Python Enhancement Proposals

  - Moved ``docs/*`` to ``docs/user/``.
  - Moved ``pysource.dtd``, ``pysource.txt``, ``semantics.txt`` from
    ``spec/`` to ``docs/dev``.
  - Moved ``doctree.txt``, ``docutils.dtd``, ``soextblx.dtd``,
    ``transforms.txt`` from ``spec/`` to ``docs/ref/``.
  - Moved ``alternatives.txt``, and ``problems.txt`` from
    ``spec/rst/`` to ``docs/dev/rst/``.
  - Moved ``reStructuredText.txt``, ``directives.txt``,
    ``interpreted.txt``, and ``introduction.txt`` from ``spec/rst/``
    to ``docs/ref/rst/``.  Renamed ``interpreted.txt`` to
    ``roles.txt``, ``reStructuredText.txt`` to
    ``restructuredtext.txt``.
  - Moved ``spec/howto/`` to ``docs/howto``.

  In order to keep the CVS history of moved files, we supplied
  SourceForge with a `script for modifying the Docutils CVS
  repository`__.

  __ http://cvs.sourceforge.net/viewcvs.py/*checkout*/docutils/sandbox/davidg/infrastructure/cvs-reorg.sh?content-type=text/plain&rev=1.5

  After running the cleanup script:

  - Added ``docs/index.txt``.
  - Added a ``.htaccess`` file to the ``web`` module, containing
    redirects for all old paths to new paths.  They'll preserve
    fragments (the "#name" part of a URL), and won't clutter up the
    file system, and will correct the URL in the user's browser.
  - Added ``BUGS.txt``, ``docs/dev/policies.txt``,
    ``docs/dev/website.txt``, ``docs/dev/release.txt`` from all but
    the "To Do" list itself in ``docs/dev/todo.txt``.
  - Moved "Future Plans" from ``HISTORY.txt`` to new "Priorities"
    section of ``docs/dev/todo.txt``.
  - Added ``THANKS.txt`` from "Acknowledgements" in ``HISTORY.txt``.
  - Added "How To Report Bugs" to ``BUGS.txt``.
  - Went through all the sources and docs (including under web/) and
    updated links.  Mostly done by Felix Wiemann; thanks Felix!
    (Still need to update links in the sandboxes.)

Specific:

* BUGS.txt: Added to project.

* THANKS.txt: Added to project.

* docutils/__init__.py:

  - 0.3.4: Post-release.

* docutils/core.py:

  - Added special error handling & advice for UnicodeEncodeError.
  - Refactored Publisher.publish (simplified exception handling &
    extracted debug dumps).
  - Renamed "enable_exit" parameter of convenience functions to
    "enable_exit_status".
  - Enabled traceback (exception propagation) by default in
    programmatic convenience functions.
  - Now publish_file and publish_cmdline convenience functions return
    the encoded string results in addition to their regular I/O.
  - Extracted common code from publish_file, publish_string, and
    publish_parts, into new publish_programmatically.  Extracted
    settings code to ``Publisher.process_programmatic_settings``.
  - In Publisher.publish, disabled ``settings_overrides`` when
    ``settings`` is supplied; redundant.

* docutils/frontend.py:

  - Added help text for "--output-encoding-error-handler" and
    "--error-encoding-error-handler".
  - Renamed "--exit" to "--exit-status".
  - Simplified default-setting code.

* docutils/parsers/rst/__init__.py:

  - Added "--pep-base-url" and "--rfc-base-url" options.

* docutils/parsers/rst/states.py:

  - Made URI recognition more aggressive and intelligent.

* docutils/parsers/rst/directives/__init__.py:

  - Added several directive option conversion functions.

* docutils/parsers/rst/directives/body.py:

  - Moved "table" directive to tables.py.

* docutils/parsers/rst/directives/tables.py: Table-related directives,
  added to project.

* docutils/writers/latex2e.py:

  - Added "--table-style=(standard|booktabs|nolines)"
  - figures get "here" option (LaTeX per default puts them at bottom),
    and figure content is centered.
  - Rowspan support for tables.
  - Fix: admonition titles before first section.
  - Replace ``--`` in literal by ``-{}-`` because fontencoding T1 has endash.
  - Replave ``_`` in literal by an underlined blank, because it has the correct
    width.
  - Fix: encode pdfbookmark titles, ``#`` broke pdflatex.
  - A few unicode replacements, if output_encoding != utf
  - Add "--graphicx-option".
  - Indent literal-blocks.
  - Fix: omit ``\maketitle`` when there is no document title.

* docs/index.txt: "Docutils Project Documentation Overview", added to
  project.

* docs/api/cmdline-tool.txt: "Inside A Docutils Command-Line Front-End
  Tool", added to project.

* docs/api/publisher.txt: "The Docutils Publisher", added to project.

* docs/api/runtime-settings.txt: "Docutils Runtime Settings", added to project.

* docs/dev/policies.txt: Added to project (extracted from
  ``docs/dev/todo.txt``, formerly ``spec/notes.txt``).

* docs/dev/release.txt: Added to project (extracted from
  ``docs/dev/todo.txt``, formerly ``spec/notes.txt``).

* docs/dev/testing.txt: Added to project.

* docs/dev/website.txt: Added to project (extracted from
  ``docs/dev/todo.txt``, formerly ``spec/notes.txt``).

* docs/ref/rst/directives.txt:

  - Added directives: "table", "csv-table".

* docs/user/rst/cheatsheet.txt: "The reStructuredText Cheat Sheet"
  added to project.  1 page for syntax, and a 1 page reference for
  directives and roles.  Source text to be used as-is; not meant to be
  converted to HTML.

* docs/user/rst/demo.txt: Added to project; moved from tools/test.txt
  with a change of title.

* test/functional/, contents, and test/test_functional.py: Added to
  project.

* tools/buildhtml.py: Fixed bug with config file handling.

* tools/html.py: Removed from project (duplicate of rst2html.py).

* tools/pep2html.py: Removed from project (duplicate of Python's
  nondist/peps/pep2html.py; Docutils' tools/pep.py can be used for
  Docutils-related PEPs in docs/peps/).

* tools/rst2pseudoxml.py: Renamed from publish.py.

* tools/rst2xml.py: Renamed from docutils-xml.py.

* tools/test.txt: Removed from project; moved to
  docs/user/rst/demo.txt.

* setup.py: Now also installs ``rst2latex.py``.


Release 0.3.3 (2004-05-09)
==========================

* docutils/__init__.py:

  - 0.3.1: Reorganized config file format (multiple sections); see
    docs/config.txt.
  - Added unknown_reference_resolvers attribute to TransformSpec.
  - 0.3.2: Interpreted text reorganization.
  - 0.3.3: Released.

* docutils/core.py:

  - Catch system messages to stop tracebacks from parsing errors.
  - Catch exceptions during processing report & exit without
    tracebacks, except when "--traceback" used.
  - Reordered components for OptionParser; application comes last.
  - Added "config_section" parameter to several methods and functions,
    allowing front ends to easily specify their config file sections.
  - Added publish_parts convenience function to allow access to individual
    parts of a document.

* docutils/examples.py: Added to project; practical examples of
  Docutils client code, to be used as-is or as models for variations.

* docutils/frontend.py:

  - Added "--traceback" & "--no-traceback" options ("traceback"
    setting).
  - Implemented support for config file reorganization:
    ``standard_config_files`` moved from ``ConfigParser`` to
    ``OptionParser``; added
    ``OptionParser.get_config_file_settings()`` and
    ``.get_standard_config_settings()``; support for old "[options]"
    section (with deprecation warning) and mapping from old to new
    settings.
  - Reimplemented setting validation.
  - Enabled flexible boolean values: yes/no, true/false, on/off.
  - Added ``Values``, a subclass of ``optparse.Values``, with support
    for list setting attributes.
  - Added support for new ``DOCUTILSCONFIG`` environment variable;
    thanks to Beni Cherniavsky.
  - Added "--no-section-numbering" option.

* docutils/io.py:

  - Catch IOErrors when opening source & destination files, report &
    exit without tracebacks.  Added ``handle_io_errors`` parameter to
    ``FileInput`` & ``FileOutput`` to enable caller error handling.

* docutils/nodes.py:

  - Changed ``SparseNodeVisitor`` and ``GenericNodeVisitor`` dynamic
    method definitions (via ``exec``) to dynamic assignments (via
    ``setattr``); thanks to Roman Suzi.
  - Encapsulated visitor dynamic assignments in a function; thanks to
    Ian Bicking.
  - Added indirect_reference_name attribute to the Targetable
    class. This attribute holds the whitespace_normalized_name
    (contains mixed case) of a target.

* docutils/statemachine.py:

  - Renamed ``StringList.strip_indent`` to ``.trim_left``.
  - Added ``StringList.get_2D_block``.

* docutils/utils.py:

  - Added "level" attribute to SystemMessage exceptions.

* docutils/languages/af.py: Added to project; Afrikaans mappings by
  Jannie Hofmeyr.

* docutils/languages/cs.py: Added to project; Czech mappings by Marek
  Blaha.

* docutils/languages/eo.py: Added to project; Esperanto mappings by
  Marcelo Huerta San Martin.

* docutils/languages/pt_br.py: Added to project; Brazilian Portuguese
  mappings by Lalo Martins.

* docutils/languages/ru.py: Added to project; Russian mappings by
  Roman Suzi.

* docutils/parsers/rst/roles.py: Added to project.  Contains
  interpreted text role functions, a registry for interpreted text
  roles, and an API for adding to and retrieving from the registry.
  Contributed by Edward Loper.

* docutils/parsers/rst/states.py:

  - Updated ``RSTState.nested_parse`` for "include" in table cells.
  - Allowed true em-dash character and "---" as block quote
    attribution marker.
  - Added support for <angle-bracketed> complex option arguments
    (option lists).
  - Fixed handling of backslashes in substitution definitions.
  - Fixed off-by-1 error with extra whitespace after substitution
    definition directive.
  - Added inline markup parsing to field lists' field names.
  - Added support for quoted (and unindented) literal blocks.
    Driven in part by a bribe from Frank Siebenlist (thanks!).
  - Parser now handles escapes in URIs correctly.
  - Made embedded-URIs' reference text omittable.  Idea from Beni
    Cherniavsky.
  - Refactored explicit target processing code.
  - Added name attribute to references containing the reference name only
    through whitespace_normalize_name (no case changes).
  - parse_target no longer returns the refname after going through
    normalize_name. This is now handled in make_target.
  - Fixed bug relating to role-less interpreted text in non-English
    contexts.
  - Reorganized interpreted text processing; moved code into the new
    roles.py module.  Contributed by Edward Loper.
  - Refactored ``Body.parse_directive`` into ``run_directive`` and
    ``parse_directive_block``.

* docutils/parsers/rst/tableparser.py:

  - Reworked for ``StringList``, to support "include" directives in
    table cells.

* docutils/parsers/rst/directives/__init__.py:

  - Renamed ``unchanged()`` directive option conversion function to
    ``unchanged_required``, and added a new ``unchanged``.
  - Catch unicode value too high error; fixes bug 781766.
  - Beefed up directive error reporting.

* docutils/parsers/rst/directives/body.py:

  - Added basic "table" directive.

* docutils/parsers/rst/directives/images.py:

  - Added "target" option to "image" directive.
  - Added name attribute to references containing the reference name only
    through whitespace_normalize_name (no case changes).

* docutils/parsers/rst/directives/misc.py:

  - Isolated the import of the ``urllib2`` module; was causing
    problems on SourceForge (``libssl.so.2`` unavailable?).
  - Added the "role" directive for declaring custom interpreted text
    roles.

* docutils/parsers/rst/directives/parts.py:

  - The "contents" directive does more work up-front, creating the
    "topic" and "title", and leaving the "pending" node for the
    transform.  Allows earlier reference resolution; fixes subtle bug.

* docutils/parsers/rst/languages/af.py: Added to project; Afrikaans
  mappings by Jannie Hofmeyr.

* docutils/parsers/rst/languages/cs.py: Added to project; Czech
  mappings by Marek Blaha.

* docutils/parsers/rst/languages/eo.py: Added to project; Esperanto
  mappings by Marcelo Huerta San Martin.

* docutils/parsers/rst/languages/pt_br.py: Added to project; Brazilian
  Portuguese mappings by Lalo Martins.

* docutils/parsers/rst/languages/ru.py: Added to project; Russian
  mappings by Roman Suzi.

* docutils/transforms/parts.py:

  - The "contents" directive does more work up-front, creating the
    "topic" and "title", and leaving the "pending" node for the
    transform.  Allows earlier reference resolution; fixes subtle bug.
  - Added support for disabling of section numbering.
    
* docutils/transforms/references.py:

  - Verifying that external targets are truly targets and not indirect 
    references. This is because we are now adding a "name" attribute to 
    references in addition to targets. Note sure if this is correct!
  - Added code to hook into the unknown_reference_resolvers list for a
    transformer in resolve_indirect_target. This allows the
    unknown_reference_resolvers to keep around indirect targets which
    docutils doesn't know about.
  - Added specific error message for duplicate targets.

* docutils/transforms/universal.py:

  - Added FilterMessages transform (removes system messages below the
    verbosity threshold).
  - Added hook (via docutils.TransformSpec.unknown_reference_resolvers)
    to FinalCheckVisitor for application-specific handling of 
    unresolvable references.
  - Added specific error message for duplicate targets.
  
* docutils/writers/__init__.py:

  - Added assemble_parts method to the Writer class to allow for
    access to a documents individual parts.
  - Documented & set default for ``Writer.output`` attribute.

* docutils/writers/html4css1.py:

  - Fixed unicode handling of attribute values (bug 760673).
  - Prevent duplication of "class" attribute values (bug report from
    Kirill Lapshin).
  - Improved table grid/border handling (prompted by report from Bob
    Marshall).
  - Added support for table titles.
  - Added "<title />" for untitled docs, for XHTML conformance; thanks
    to Darek Suchojad.
  - Added functionality to keep track of individual parts of a document
    and store them in a dictionary as the "parts" attribute of the writer.
    Contributed by Reggie Dugard at the Docutils sprint at PyCon DC 2004.
  - Added proper support for the "scale" attribute of the "image"
    element.  Contributed by Brent Cook.
  - Added ``--initial-header-level`` option.
  - Fixed bug: the body_pre_docinfo segment depended on there being a
    docinfo; if no docinfo, the document title was incorporated into
    the body segment.  Adversely affected the publish_parts interface.

* docutils/writers/latex2e.py:

  - Changed default stylesheet to "no stylesheet" to avoid latex complaining
    about a missing file.
  - Added options and support: ``--compound-enumerators``,
    ``--section-prefix-for-enumerators``, and
    ``--section-enumerator-separator``.  By John F Meinel Jr (SF patch
    934322).
  - Added option ``--use-verbatim-when-possible``, to avoid
    problematic characters (eg, '~' in italian) in literal blocks.
  - It's now possible to use four section levels in the `book` and
    `report` LaTeX classes.  The default `article` class still has
    three levels limit.
    
* docs/config.txt: "Docutils Configuration Files", added to project.
  Moved config file entry descriptions from tools.txt.

* docs/tools.txt:

  - Moved config file entry descriptions to config.txt.

* spec/notes.txt: Continual updates.  Added "Setting Up For Docutils
  Development".

* spec/howto/rst-roles.txt: "Creating reStructuredText Interpreted
  Text Roles", added to project.

* spec/rst/reStructuredText.txt:

  - Added description of support for <angle-bracketed> complex option
    arguments to option lists.
  - Added subsections for indented and quoted literal blocks.

* test: Continually adding & updating tests.

  - Added test/test_settings.py & test/data/config_*.txt support
    files.
  - Added test/test_writers/test_htmlfragment.py.

* test/DocutilsTestSupport.py:

  - Refactored LaTeX publisher test suite/case class names to make
    testing other writers easier.
  - Added HtmlWriterPublishTestCase and HtmlFragmentTestSuite classes
    to test the processing of HTML fragments which use the new
    publish_parts convenience function.

* tools/buildhtml.py:

  - Added support for the "--prune" option.
  - Removed dependency on pep2html.py; plaintext PEPs no longer
    supported.

* tools/docutils.conf:

  - Updated for configuration file reorganization.

* tools/rst2html.py:

  - copied from tools/html.py

* setup.py:

  - added a 'scripts' section to configuration
  - added 'tools/rst2html.py' to the scripts section


Release 0.3 (2003-06-24)
========================

General:

* Renamed "attribute" to "option" for directives/extensions.

* Renamed transform method "transform" to "apply".

* Renamed "options" to "settings" for runtime settings (as set by
  command-line options).  Sometimes "option" (singular) became
  "settings" (plural).  Some variations below:

  - document.options -> document.settings (stored in other objects as
    well)
  - option_spec -> settings_spec (not directives though)
  - OptionSpec -> SettingsSpec
  - cmdline_options -> settings_spec
  - relative_path_options -> relative_path_settings
  - option_default_overrides -> settings_default_overrides
  - Publisher.set_options -> Publisher.get_settings

Specific:

* COPYING.txt: Added "Public Domain Dedication".

* FAQ.txt: Frequently asked questions, added to project.

* setup.py:

  - Updated with PyPI Trove classifiers.
  - Conditional installation of third-party modules.

* docutils/__init__.py:

  - Bumped version to 0.2.1 to reflect changes to I/O classes.
  - Bumped version to 0.2.2 to reflect changes to stylesheet options.
  - Factored ``SettingsSpec`` out of ``Component``; separately useful.
  - Bumped version to 0.2.3 because of the new "--embed-stylesheet"
    option and its effect on the PEP template & writer.
  - Bumped version to 0.2.4 due to changes to the PEP template &
    stylesheet.
  - Bumped version to 0.2.5 to reflect changes to Reporter output.
  - Added ``TransformSpec`` class for new transform system.
  - Bumped version to 0.2.6 for API changes (renaming).
  - Bumped version to 0.2.7 for new ``docutils.core.publish_*``
    convenience functions.
  - Added ``Component.component_type`` attribute.
  - Bumped version to 0.2.8 because of the internal parser switch from
    plain lists to the docutils.statemachine.StringList objects.
  - Bumped version to 0.2.9 because of the frontend.py API changes.
  - Bumped version to 0.2.10 due to changes to the project layout
    (third-party modules removed from the "docutils" package), and
    signature changes in ``io.Input``/``io.Output``.
  - Changed version to 0.3.0 for release.

* docutils/core.py:

  - Made ``publish()`` a bit more convenient.
  - Generalized ``Publisher.set_io``.
  - Renamed ``publish()`` to ``publish_cmdline()``; rearranged its
    parameters; improved its docstring.
  - Added ``publish_file()`` and ``publish_string()``.
  - Factored ``Publisher.set_source()`` and ``.set_destination()``
    out of ``.set_io``.
  - Added support for "--dump-pseudo-xml", "--dump-settings", and
    "--dump-transforms" hidden options.
  - Added ``Publisher.apply_transforms()`` method.
  - Added ``Publisher.set_components()`` method; support for
    ``publish_*()`` conveninece functions.
  - Moved config file processing to docutils/frontend.py.
  - Added support for exit status ("exit_level" setting &
    ``enable_exit`` parameter for Publisher.publish() and convenience
    functions).

* docutils/frontend.py:

  - Check for & exit on identical source & destination paths.
  - Fixed bug with absolute paths & "--config".
  - Set non-command-line defaults in ``OptionParser.__init__()``:
    ``_source`` & ``_destination``.
  - Distributed ``relative_path_settings`` to components; updated
    ``OptionParser.populate_from_components()`` to combine it all.
  - Require list of keys in ``make_paths_absolute`` (was implicit in
    global ``relative_path_settings``).
  - Added "--expose-internal-attribute", "--dump-pseudo-xml",
    "--dump-settings", and "--dump-transforms" hidden options.
  - Removed nasty internals-fiddling ``ConfigParser.get_section``
    code, replaced with correct code.
  - Added validation functionality for config files.
  - Added "--error-encoding" option/setting, "_disable_config"
    internal setting.
  - Added encoding validation; updated "--input-encoding" and
    "--output-encoding"; added "--error-encoding-error-handler" and
    "--output-encoding-error-handler".
  - Moved config file processing from docutils/core.py.
  - Updated ``OptionParser.populate_from_components`` to handle new
    ``SettingsSpec.settings_defaults`` dict.
  - Added support for "-" => stdin/stdout.
  - Added "exit_level" setting ("--exit" option).

* docutils/io.py:

  - Split ``IO`` classes into subclasses of ``Input`` and ``Output``.
  - Added automatic closing to ``FileInput`` and ``FileOutput``.
  - Delayed opening of ``FileOutput`` file until ``write()`` called.
  - ``FileOutput.write()`` now returns the encoded output string.
  - Try to get path/stream name automatically in ``FileInput`` &
    ``FileOutput``.
  - Added defaults for source & destination paths.
  - Allow for Unicode I/O with an explicit "unicode" encoding.
  - Added ``Output.encode()``.
  - Removed dependency on runtime settings; pass encoding directly.
  - Recognize Unicode strings in ``Input.decode()``.
  - Added support for output encoding error handlers.

* docutils/nodes.py:

  - Added "Invisible" element category class.
  - Changed ``Node.walk()`` & ``.walkabout()`` to permit more tree
    modification during a traversal.
  - Added element classes: ``line_block``, ``generated``, ``address``,
    ``sidebar``, ``rubric``, ``attribution``, ``admonition``,
    ``superscript``, ``subscript``, ``inline``
  - Added support for lists of nodes to ``Element.insert()``.
  - Fixed parent linking in ``Element.replace()``.
  - Added new abstract superclass ``FixedTextElement``; adds
    "xml:space" attribute.
  - Added support for "line" attribute of ``system_message`` nodes.
  - Added support for the observer pattern from ``utils.Reporter``.
    Added ``parse_messages`` and ``transform_messages`` attributes to
    ``document``, removed ``messages``.  Added ``note_parse_message``
    and ``note_transform_message`` methods.
  - Added support for improved diagnostics:

    - Added "document", "source", and "line" internal attributes to
      ``Node``, set by ``Node.setup_child()``.
    - Converted variations on ``node.parent = self`` to
      ``self.setup_child(node)``.
    - Added ``document.current_source`` & ``.current_line``
      attributes, and ``.note_source`` observer method.
    - Changed "system_message" output to GNU-Tools format.

  - Added a "rawsource" attribute to the ``Text`` class, for text
    before backslash-escape resolution.
  - Support for new transform system.
  - Reworked ``pending`` element.
  - Fixed XML DOM bug (SF #660611).
  - Removed the ``interpeted`` element class and added
    ``title_reference``, ``abbreviation``, ``acronym``.
  - Made substitutions case-sensitive-but-forgiving; moved some code
    from the parser.
  - Fixed Unicode bug on element attributes (report: William Dode).

* docutils/optik.py: Removed from project; replaced with
  extras/optparse.py and extras/textwrap.py.  These will be installed
  only if they're not already present in the Python installation.

* docutils/roman.py: Moved to extras/roman.py; this will be installed
  only if it's not already present in the Python installation.

* docutils/statemachine.py:

  - Factored out ``State.add_initial_transitions()`` so it can be
    extended.
  - Converted whitespace-specific "blank" and "indent" transitions
    from special-case code to ordinary transitions: removed
    ``StateMachineWS.check_line()`` & ``.check_whitespace()``, added
    ``StateWS.add_initial_transitions()`` method, ``ws_patterns`` &
    ``ws_initial_transitions`` attributes.
  - Removed ``State.match_transition()`` after merging it into
    ``.check_line()``.
  - Added ``StateCorrection`` exception.
  - Added support for ``StateCorrection`` in ``StateMachine.run()``
    (moved ``TransitionCorrection`` support there too.)
  - Changed ``StateMachine.next_line()`` and ``.goto_line()`` to raise
    ``EOFError`` instead of ``IndexError``.
  - Added ``State.no_match`` method.
  - Added support for the Observer pattern, triggered by input line
    changes.
  - Added ``strip_top`` parameter to
    ``StateMachineWS.get_first_known_indented``.
  - Made ``context`` a parameter to ``StateMachine.run()``.
  - Added ``ViewList`` & ``StringList`` classes;
    ``extract_indented()`` becomes ``StringList.get_indented()``.
  - Added ``StateMachine.insert_input()``.
  - Fixed ViewList slice handling for Python 2.3.  Patch from (and
    thanks to) Fred Drake.

* docutils/utils.py:

  - Added a ``source`` attribute to Reporter instances and
    ``system_message`` elements.
  - Added an observer pattern to ``utils.Reporter`` to keep track of
    system messages.
  - Fixed bugs in ``relative_path()``.
  - Added support for improved diagnostics.
  - Moved ``normalize_name()`` to nodes.py (``fully_normalize_name``).
  - Added support for encoding Reporter stderr output, and encoding
    error handlers.
  - Reporter keeps track of the highest level system message yet
    generated.

* docutils/languages: Fixed bibliographic field language lookups.

* docutils/languages/es.py: Added to project; Spanish mappings by
  Marcelo Huerta San Martin.

* docutils/languages/fr.py: Added to project; French mappings by
  Stefane Fermigier.

* docutils/languages/it.py: Added to project; Italian mappings by
  Nicola Larosa.

* docutils/languages/sk.py: Added to project; Slovak mappings by
  Miroslav Vasko.

* docutils/parser/__init__.py:

  - Added ``Parser.finish_parse()`` method.

* docutils/parser/rst/__init__.py:

  - Added options: "--pep-references", "--rfc-references",
    "--tab-width", "--trim-footnote-reference-space".

* docutils/parsers/rst/states.py:

  - Changed "title under/overline too short" system messages from INFO
    to WARNING, and fixed its insertion location.
  - Fixed enumerated list item parsing to allow paragraphs & section
    titles to begin with enumerators.
  - Converted system messages to use the new "line" attribute.
  - Fixed a substitution reference edge case.
  - Added support for "--pep-references" and "--rfc-references"
    options; reworked ``Inliner`` code to make customization easier.
  - Removed field argument parsing.
  - Added support for short section title over/underlines.
  - Fixed "simple reference name" regexp to ignore text like
    "object.__method__"; not an anonymous reference.
  - Added support for improved diagnostics.
  - Reworked directive API, based on Dethe Elza's contribution.  Added
    ``Body.parse_directive()``, ``.parse_directive_options()``,
    ``.parse_directive_arguments()`` methods.
  - Added ``ExtensionOptions`` class, to parse directive options
    without parsing field bodies.  Factored
    ``Body.parse_field_body()`` out of ``Body.field()``, overridden in
    ``ExtensionOptions``.
  - Improved definition list term/classifier parsing.
  - Added warnings for unknown directives.
  - Renamed ``Stuff`` to ``Struct``.
  - Now flagged as errors: transitions at the beginning or end of
    sections, empty sections (except title), and empty documents.
  - Updated for ``statemachine.StringList``.
  - Enabled recognition of schemeless email addresses in targets.
  - Added support for embedded URIs in hyperlink references.
  - Added backslash-escapes to inline markup end-string suffix.
  - Added support for correct interpreted text processing.
  - Fixed nested title parsing (topic, sidebar directives).
  - Added special processing of backslash-escaped whitespace (idea
    from David Abrahams).
  - Made substitutions case-sensitive-but-forgiving; moved some code
    to ``docutils.nodes``.
  - Added support for block quote attributions.
  - Added a kludge to work-around a conflict between the bubble-up
    parser strategy and short titles (<= 3 char-long over- &
    underlines).  Fixes SF bug #738803 "infinite loop with multiple
    titles" submitted by Jason Diamond.
  - Added explicit interpreted text roles for standard inline markup:
    "emphasis", "strong", "literal".
  - Implemented "superscript" and "subscript" interpreted text roles.
  - Added initial support for "abbreviation" and "acronym" roles;
    incomplete.
  - Added support for "--trim-footnote-reference-space" option.
  - Optional space before colons in directives & hyperlink targets.

* docutils/parsers/rst/tableparser.py:

  - Fixed a bug that was producing unwanted empty rows in "simple"
    tables.
  - Detect bad column spans in "simple" tables.

* docutils/parsers/rst/directives: Updated all directive functions to
  new API.

* docutils/parsers/rst/directives/__init__.py:

  - Added ``flag()``, ``unchanged()``, ``path()``,
    ``nonnegative_int()``, ``choice()``, and ``class_option()``
    directive option helper functions.
  - Added warnings for unknown directives.
  - Return ``None`` for missing directives.
  - Added ``register_directive()``, thanks to William Dode and Paul
    Moore.

* docutils/parsers/rst/directives/admonitions.py:

  - Added "admonition" directive.

* docutils/parsers/rst/directives/body.py: Added to project.  Contains
  the "topic", "sidebar" (from Patrick O'Brien), "line-block",
  "parsed-literal", "rubric", "epigraph", "highlights" and
  "pull-quote" directives.

* docutils/parsers/rst/directives/images.py:

  - Added an "align" attribute to the "image" & "figure" directives
    (by Adam Chodorowski).
  - Added "class" option to "image", and "figclass" to "figure".

* docutils/parsers/rst/directives/misc.py:

  - Added "include", "raw", and "replace" directives, courtesy of
    Dethe Elza.
  - Added "unicode" and "class" directives.

* docutils/parsers/rst/directives/parts.py:

  - Added the "sectnum" directive; by Dmitry Jemerov.
  - Added "class" option to "contents" directive.

* docutils/parsers/rst/directives/references.py: Added to project.
  Contains the "target-notes" directive.

* docutils/parsers/rst/languages/__init__.py:

  - Return ``None`` from get_language() for missing language modules.

* docutils/parsers/rst/languages/de.py: Added to project; German
  mappings by Engelbert Gruber.

* docutils/parsers/rst/languages/en.py:

  - Added interpreted text roles mapping.

* docutils/parsers/rst/languages/es.py: Added to project; Spanish
  mappings by Marcelo Huerta San Martin.

* docutils/parsers/rst/languages/fr.py: Added to project; French
  mappings by William Dode.

* docutils/parsers/rst/languages/it.py: Added to project; Italian
  mappings by Nicola Larosa.

* docutils/parsers/rst/languages/sk.py: Added to project; Slovak
  mappings by Miroslav Vasko.

* docutils/readers/__init__.py:

  - Added support for the observer pattern from ``utils.Reporter``, in
    ``Reader.parse`` and ``Reader.transform``.
  - Removed ``Reader.transform()`` method.
  - Added default parameter values to ``Reader.__init__()`` to make
    instantiation easier.
  - Removed bogus aliases: "restructuredtext" is *not* a Reader.

* docutils/readers/pep.py:

  - Added the ``peps.TargetNotes`` transform to the Reader.
  - Removed PEP & RFC reference detection code; moved to
    parsers/rst/states.py as options (enabled here by default).
  - Added support for pre-acceptance PEPs (no PEP number yet).
  - Moved ``Inliner`` & made it a class attribute of ``Reader`` for
    easy subclassing.

* docutils/readers/python: Python Source Reader subpackage added to
  project, including preliminary versions of:

  - __init__.py
  - moduleparser.py: Parser for Python modules.

* docutils/transforms/__init__.py:

  - Added ``Transformer`` class and completed transform reform.
  - Added unknown_reference_resolvers list for each transformer. This list holds
    the list of functions provided by each component of the transformer that
    help resolve references.

* docutils/transforms/frontmatter.py:

  - Improved support for generic fields.
  - Fixed bibliographic field language lookups.

* docutils/transforms/misc.py: Added to project.  Miscellaneous
  transforms.

* docutils/transforms/parts.py:

  - Moved the "id" attribute from TOC list items to the references
    (``Contents.build_contents()``).
  - Added the ``SectNum`` transform; by Dmitry Jemerov.
  - Added "class" attribute support to ``Contents``.

* docutils/transforms/peps.py:

  - Added ``mask_email()`` function, updating to pep2html.py's
    functionality.
  - Linked "Content-Type: text/x-rst" to PEP 12.
  - Added the ``TargetNotes`` PEP-specific transform.
  - Added ``TargetNotes.cleanup_callback``.
  - Added title check to ``Headers``.

* docutils/transforms/references.py:

  - Added the ``TargetNotes`` generic transform.
  - Split ``Hyperlinks`` into multiple transforms.
  - Fixed bug with multiply-indirect references (report: Bruce Smith).
  - Added check for circular indirect references.
  - Made substitutions case-sensitive-but-forgiving.

* docutils/transforms/universal.py:

  - Added support for the "--expose-internal-attributes" option.
  - Removed ``Pending`` transform classes & data.

* docutils/writers/__init__.py:

  - Removed ``Writer.transform()`` method.

* docutils/writers/docutils-xml.py:

  - Added XML and doctype declarations.
  - Added "--no-doctype" and "--no-xml-declaration" options.

* docutils/writers/html4css1.py:

  - "name" attributes only on these tags: a, applet, form, frame,
    iframe, img, map.
  - Added "name" attribute to <a> in section titles for Netscape 4
    support (bug report: Pearu Peterson).
  - Fixed targets (names) on footnote, citation, topic title,
    problematic, and system_message nodes (for Netscape 4).
  - Changed field names from "<td>" to "<th>".
  - Added "@" to "@" encoding to thwart address harvesters.
  - Improved the vertical whitespace optimization; ignore "invisible"
    nodes (targets, comments, etc.).
  - Improved inline literals with ``<span class="pre">`` around chunks
    of text and `` `` for runs of spaces.
  - Improved modularity of output; added ``self.body_pre_docinfo`` and
    ``self.docinfo`` segments.
  - Added support for "line_block", "address" elements.
  - Improved backlinks (footnotes & system_messages).
  - Improved system_message output.
  - Redefined "--stylesheet" as containing an invariant URL, used
    verbatim.  Added "--stylesheet-path", interpreted w.r.t. the
    working directory.
  - Added "--footnote-references" option (superscript or brackets).
  - Added "--compact-lists" and "--no-compact-lists" options.
  - Added "--embed-stylesheet" and "--link-stylesheet" options;
    factored out ``HTMLTranslator.get_stylesheet_reference()``.
  - Improved field list rendering.
  - Added Docutils version to "generator" meta tag.
  - Fixed a bug with images; they must be inline, so wrapped in <p>.
  - Improved layout of <pre> HTML source.
  - Fixed attribute typo on <colspec>.
  - Refined XML prologue.
  - Support for no stylesheet.
  - Removed "interpreted" element support.
  - Added support for "title_reference", "sidebar", "attribution",
    "rubric", and generic "admonition" elements.
  - Added "--attribution" option.
  - Added support for "inline", "subscript", "superscript" elements.
  - Added initial support for "abbreviation" and "acronym";
    incomplete.

* docutils/writers/latex2e.py: LaTeX Writer, added by Engelbert Gruber
  (from the sandbox).

  - Added french.
  - Double quotes in literal blocks (special treatment for de/ngerman).
  - Added '--hyperlink-color' option ('0' turns off coloring of links).
  - Added  "--attribution" option.
  - Right align attributions.

* docutils/writers/pep_html.py:

  - Parameterized output encoding in PEP template.
  - Reworked substitutions from ``locals()`` into ``subs`` dict.
  - Redefined "--pep-stylesheet" as containing an invariant URL, used
    verbatim.  Added "--pep-stylesheet-path", interpreted w.r.t. the
    working directory.
  - Added an override on the "--footnote-references" option.
  - Factored out ``HTMLTranslator.get_stylesheet_reference()``.
  - Added Docutils version to "generator" meta tag.
  - Added a "DO NOT EDIT THIS FILE" comment to generated HTML.

* docs/tools.txt:

  - Added a "silent" setting for ``buildhtml.py``.
  - Added a "Getting Help" section.
  - Rearranged the structure.
  - Kept up to date, with new settings, command-line options etc.
  - Added section for ``rst2latex.py`` (Engelbert Gruber).
  - Converted settings table into a definition list.

* docs/rst/quickstart.txt:

  - Added a table of contents.
  - Added feedback information.
  - Added mention of minimum section title underline lengths.
  - Removed the 4-character minimum for section title underlines.

* docs/rst/quickref.html:

  - Added a "Getting Help" section.
  - Added a style to make section title backlinks more subtle.
  - Added mention of minimum section title underline lengths.
  - Removed the 4-character minimum for section title underlines.

* extras: Directory added to project; contains third-party modules
  that Docutils depends on (optparse, textwrap, roman).  These are
  only installed if they're not already present.

* licenses: Directory added to project; contains copies of license
  files for non-public-domain files.

* spec/doctree.txt:

  - Changed the focus.  It's about DTD elements:  structural
    relationships, semantics, and external (public) attributes.  Not
    about the element class library.
  - Moved some implementation-specific stuff into ``docutils.nodes``
    docstrings.
  - Wrote descriptions of all common attributes and parameter
    entities.  Filled in introductory material.
  - Working through the element descriptions: 55 down, 37 to go.
  - Removed "Representation of Horizontal Rules" to
    spec/rst/alternatives.txt.

* spec/docutils.dtd:

  - Added "generated" inline element.
  - Added "line_block" body element.
  - Added "auto" attribute to "title".
  - Changed content models of "literal_block" and "doctest_block" to
    ``%text.model``.
  - Added ``%number;`` attribute type parameter entity.
  - Changed ``%structural.elements;`` to ``%section.elements``.
  - Updated attribute types; made more specific.
  - Added "address" bibliographic element.
  - Added "line" attribute to ``system_message`` element.
  - Removed "field_argument" element; "field_name" may contain
    multiple words and whitespace.
  - Changed public identifier to docutils.sf.net.
  - Removed "interpreted" element; added "title_reference",
    "abbreviation", "acronym".
  - Removed "refuri" attribute from "footnote_reference" and
    "citation_reference".
  - Added "sidebar", "rubric", "attribution", "admonition",
    "superscript", "subscript", and "inline" elements.

* spec/pep-0256.txt: Converted to reStructuredText & updated.

* spec/pep-0257.txt: Converted to reStructuredText & updated.

* spec/pep-0258.txt: Converted to reStructuredText & updated.

* spec/semantics.txt: Updated with text from a Doc-SIG response to
  Dallas Mahrt.

* spec/transforms.txt: Added to project.

* spec/howto: Added subdirectory, for developer how-to docs.

* spec/howto/rst-directives.txt: Added to project.  Original by Dethe
  Elza, edited & extended by David Goodger.

* spec/howto/i18n.txt: Docutils Internationalization.  Added to
  project.

* spec/rst/alternatives.txt:

  - Added "Doctree Representation of Transitions" from
    spec/doctree.txt.
  - Updated "Inline External Targets" & closed the debate.
  - Added ideas for interpreted text syntax extensions.
  - Added "Nested Inline Markup" section.

* spec/rst/directives.txt:

  - Added directives: "topic", "sectnum", "target-notes",
    "line-block", "parsed-literal", "include", "replace", "sidebar",
    "admonition", "rubric", "epigraph", "highlights", "unicode" and
    "class".
  - Formalized descriptions of directive details.
  - Added an "align" attribute to the "image" & "figure" directives
    (by Adam Chodorowski).
  - Added "class" options to "topic", "sidebar", "line-block",
    "parsed-literal", "contents", and "image"; and "figclass" to
    "figure".

* spec/rst/interpreted.txt: Added to project.  Descriptions of
  interpreted text roles.

* spec/rst/introduction.txt:

  - Added pointers to material for new users.

* spec/rst/reStructuredText.txt:

  - Disambiguated comments (just add a newline after the "::").
  - Updated enumerated list description; added a discussion of the
    second-line validity checking.
  - Updated directive description.
  - Added a note redirecting newbies to the user docs.
  - Expanded description of inline markup start-strings in non-markup
    contexts.
  - Removed field arguments and made field lists a generic construct.
  - Removed the 4-character minimum for section title underlines.
  - Clarified term/classifier delimiter & inline markup ambiguity
    (definition lists).
  - Added "Embedded URIs".
  - Updated "Interpreted Text" section.
  - Added "Character-Level Inline Markup" section.

* test: Continually adding & updating tests.

  - Moved test/test_rst/ to test/test_parsers/test_rst/.
  - Moved test/test_pep/ to test/test_readers/test_pep/.
  - Added test/test_readers/test_python/.
  - Added test/test_writers/ (Engelbert Gruber).

* tools:

  - Made the ``locale.setlocale()`` calls in front ends
    fault-tolerant.

* tools/buildhtml.py:

  - Added "--silent" option.
  - Fixed bug with absolute paths & "--config".
  - Updated for new I/O classes.
  - Added some exception handling.
  - Separated publishers' setting defaults; prevents interference.
  - Updated for new ``publish_file()`` convenience function.

* tools/pep-html-template:

  - Allow for "--embed-stylesheet".
  - Added Docutils version to "generator" meta tag.
  - Added a "DO NOT EDIT THIS FILE" comment to generated HTML.
  - Conform to XHTML spec.

* tools/pep2html.py:

  - Made ``argv`` a parameter to ``main()``.
  - Added support for "Content-Type:" header & arbitrary PEP formats.
  - Linked "Content-Type: text/plain" to PEP 9.
  - Files skipped (due to an error) are not pushed onto the server.
  - Updated for new I/O classes.
  - Added ``check_requirements()`` & ``pep_type_error()``.
  - Added some exception handling.
  - Updated for new ``publish_string()`` convenience function.
  - Added a "DO NOT EDIT THIS FILE" comment to generated HTML.

* tools/quicktest.py:

  - Added "-V"/"--version" option.

* tools/rst2latex.py: LaTeX front end, added by Engelbert Gruber.

* tools/unicode2rstsubs.py: Added to project.  Produces character
  entity files (reSructuredText substitutions) from the MathML master
  unicode.xml file.

* tools/editors: Support code for editors, added to project.  Contains
  ``emacs/restructuredtext.el``.

* tools/stylesheets/default.css: Moved into the stylesheets directory.

  - Added style for chunks of inline literals.
  - Removed margin for first child of table cells.
  - Right-aligned field list names.
  - Support for auto-numbered section titles in TOCs.
  - Increased the size of inline literals (<tt>) in titles.
  - Restored the light gray background for inline literals.
  - Added support for "line_block" elements.
  - Added style for "address" elements.
  - Removed "a.footnote-reference" style; doing it with ``<sup>`` now.
  - Improved field list rendering.
  - Vertical whitespace improvements.
  - Removed "a.target" style.

* tools/stylesheets/pep.css:

  - Fixed nested section margins.
  - Other changes parallel those of ``../default.css``.


Release 0.2 (2002-07-31)
========================

General:

- The word "component" was being used ambiguously.  From now on,
  "component" will be used to mean "Docutils component", as in Reader,
  Writer, Parser, or Transform.  Portions of documents (Table of
  Contents, sections, etc.)  will be called "document parts".
- Did a grand renaming: a lot of ``verylongnames`` became
  ``very_long_names``.
- Cleaned up imports: no more relative package imports or
  comma-separated lists of top-level modules.
- Added support for an option values object which carries default
  settings and overrides (from command-line options and library use).
- Added internal Unicode support, and support for both input and
  output encodings.
- Added support for the ``docutils.io.IO`` class & subclasses.

Specific:

* docutils/__init__.py:

  - Added ``ApplicationError`` and ``DataError``, for use throughout
    the package.
  - Added ``Component`` base class for Docutils components; implements
    the ``supports`` method.
  - Added ``__version__`` (thus, ``docutils.__version__``).

* docutils/core.py:

  - Removed many keyword parameters to ``Publisher.__init__()`` and
    ``publish()``; bundled into an option values object.  Added
    "argv", "usage", "description", and "option_spec" parameters for
    command-line support.
  - Added ``Publisher.process_command_line()`` and ``.set_options()``
    methods.
  - Reworked I/O model for ``docutils.io`` wrappers.
  - Updated ``Publisher.set_options()``; now returns option values
    object.
  - Added support for configuration files (/etc/docutils.conf,
    ./docutils.conf, ~/.docutils).
  - Added ``Publisher.setup_option_parser()``.
  - Added default usage message and description.

* docutils/frontend.py: Added to project; support for front-end
  (command-line) scripts.  Option specifications may be augmented by
  components.  Requires Optik (http://optik.sf.net/) for option
  processing (installed locally as docutils/optik.py).

* docutils/io.py: Added to project; uniform API for a variety of input
  output mechanisms.

* docutils/nodes.py:

  - Added ``TreeCopyVisitor`` class.
  - Added a ``copy`` method to ``Node`` and subclasses.
  - Added a ``SkipDeparture`` exception for visitors.
  - Renamed ``TreePruningException`` from ``VisitorException``.
  - Added docstrings to ``TreePruningException``, subclasses, and
    ``Nodes.walk()``.
  - Improved docstrings.
  - Added ``SparseNodeVisitor``, refined ``NodeVisitor``.
  - Moved ``utils.id()`` to ``nodes.make_id()`` to avoid circular
    imports.
  - Added ``decoration``, ``header``, and ``footer`` node classes, and
    ``PreDecorative`` mixin.
  - Reworked the name/id bookkeeping; to ``document``, removed
    ``explicit_targets`` and ``implicit_targets`` attributes, added
    ``nametypes`` attribute and ``set_name_id_map`` method.
  - Added ``NodeFound`` exception, for use with ``NodeVisitor``
    traversals.
  - Added ``document.has_name()`` method.
  - Fixed DOM generation for list-attributes.
  - Added category class ``Labeled`` (used by footnotes & citations).
  - Added ``Element.set_class()`` method (sets "class" attribute).

* docutils/optik.py: Added to project.  Combined from the Optik
  package, with added option groups and other modifications.  The use
  of this module is probably only temporary.

* docutils/statemachine.py:

  - Added ``runtime_init`` method to ``StateMachine`` and ``State``.
  - Added underscores to improve many awkward names.
  - In ``string2lines()``, changed whitespace normalizing translation
    table to regexp; restores Python 2.0 compatibility with Unicode.

* docutils/urischemes.py:

  - Filled in some descriptions.
  - Added "shttp" scheme.

* docutils/utils.py:

  - Added ``clean_rcs_keywords`` function (moved from
    docutils/transforms/frontmatter.py
    ``DocInfo.filter_rcs_keywords``).
  - Added underscores to improve many awkward names.
  - Changed names of Reporter's thresholds:
    warning_level -> report_level; error_level -> halt_level.
  - Moved ``utils.id()`` to ``nodes.make_id()``.
  - Added ``relative_path(source, target)``.

* docutils/languages/de.py: German mappings; added to project.  Thanks
  to Gunnar Schwant for the translations.

* docutils/languages/en.py: Added "Dedication" bibliographic field
  mappings.

* docutils/languages/sv.py: Swedish mappings; added to project by Adam
  Chodorowski.

* docutils/parsers/rst/states.py:

  - Added underscores to improve many awkward names.
  - Added RFC-2822 header support.
  - Extracted the inline parsing code from ``RSTState`` to a separate
    class, ``Inliner``, which will allow easy subclassing.
  - Made local bindings for ``memo`` container & often-used contents
    (reduces code complexity a lot).  See ``RSTState.runtime_init()``.
  - ``RSTState.parent`` replaces ``RSTState.statemachine.node``.
  - Added ``MarkupMismatch`` exception; for late corrections.
  - Added ``-/:`` characters to inline markup's start string prefix,
    ``/`` to end string suffix.
  - Fixed a footnote bug.
  - Fixed a bug with literal blocks.
  - Applied patch from Simon Budig: simplified regexps with symbolic
    names, removed ``Inliner.groups`` and ``Body.explicit.groups``.
  - Converted regexps from ``'%s' % var`` to ``'%(var)s' % locals()``.
  - Fixed a bug in ``Inliner.interpreted_or_phrase_ref()``.
  - Allowed non-ASCII in "simple names" (directive names, field names,
    references, etc.).
  - Converted ``Inliner.patterns.initial`` to be dynamically built
    from parts with ``build_regexp()`` function.
  - Changed ``Inliner.inline_target`` to ``.inline_internal_target``.
  - Updated docstrings.
  - Changed "table" to "grid_table"; added "simple_table" support.

* docutils/parsers/rst/tableparser.py:

  - Changed ``TableParser`` to ``GridTableParser``.
  - Added ``SimpleTableParser``.
  - Refactored naming.

* docutils/parsers/rst/directives/__init__.py: Added "en" (English) as
  a fallback language for directive names.

* docutils/parsers/rst/directives/html.py: Changed the ``meta``
  directive to use a ``pending`` element, used only by HTML writers.

* docutils/parsers/rst/directives/parts.py: Renamed from
  components.py.

  - Added "backlinks" attribute to "contents" directive.

* docutils/parsers/rst/languages/sv.py: Swedish mappings; added to
  project by Adam Chodorowski.

* docutils/readers/__init__.py: Gave Readers more control over
  choosing and instantiating Parsers.

* docutils/readers/pep.py: Added to project; for PEP processing.

* docutils/transforms/__init__.py: ``Transform.__init__()`` now
  requires a ``component`` parameter.

* docutils/transforms/components.py: Added to project; transforms
  related to Docutils components.

* docutils/transforms/frontmatter.py:

  - In ``DocInfo.extract_authors``, check for a single "author" in an
    "authors" group, and convert it to a single "author" element.
  - Added support for "Dedication" and generic bibliographic fields.

* docutils/transforms/peps.py: Added to project; PEP-specific.

* docutils/transforms/parts.py: Renamed from old components.py.

  - Added filter for `Contents`, to use alt-text for inline images,
    and to remove inline markup that doesn't make sense in the ToC.
  - Added "name" attribute to TOC topic depending on its title.
  - Added support for optional TOC backlinks.

* docutils/transforms/references.py: Fixed indirect target resolution
  in ``Hyperlinks`` transform.

* docutils/transforms/universal.py:

  - Changed ``Messages`` transform to properly filter out system
    messages below the warning threshold.
  - Added ``Decorations`` transform (support for ``--generator``,
    ``--date``, ``--time``, ``--source-link`` options).

* docutils/writers/__init__.py: Added "pdf" alias in anticipation of
  Engelbert Gruber's PDF writer.

* docutils/writers/html4css1.py:

  - Made XHTML-compatible (switched to lowercase element & attribute
    names; empty tag format).
  - Escape double-dashes in comment text.
  - Improved boilerplate & modularity of output.
  - Exposed modular output in Writer class.
  - Added a "generator" meta tag to <head>.
  - Added support for the ``--stylesheet`` option.
  - Added support for ``decoration``, ``header``, and ``footer``
    elements.
  - In ``HTMLTranslator.attval()``, changed whitespace normalizing
    translation table to regexp; restores Python 2.0 compatibility
    with Unicode.
  - Added the translator class as instance variable to the Writer, to
    make it easily subclassable.
  - Improved option list spacing (thanks to Richard Jones).
  - Modified field list output.
  - Added backlinks to footnotes & citations.
  - Added percentage widths to "<col>" tags (from colspec).
  - Option lists: "<code>" changed to "<kbd>", ``option_argument``
    "<span>" changed to "<var>".
  - Inline literals: "<code>" changed to "<tt>".
  - Many changes to optimize vertical space: compact simple lists etc.
  - Add a command-line options & directive attributes to control TOC
    and footnote/citation backlinks.
  - Added support for optional footnote/citation backlinks.
  - Added support for generic bibliographic fields.
  - Identify backrefs.
  - Relative URLs for stylesheet links.

* docutils/writers/pep_html.py: Added to project; HTML Writer for
  PEPs (subclass of ``html4css1.Writer``).

* docutils/writers/pseudoxml.py: Renamed from pprint.py.

* docutils/writers/docutils_xml.py: Added to project; trivial writer
  of the Docutils internal doctree in XML.

* docs/tools.txt: "Docutils Front-End Tools", added to project.

* spec/doctree.txt:

  - Changed the title to "The Docutils Document Tree".
  - Added "Hyperlink Bookkeeping" section.

* spec/docutils.dtd:

  - Added ``decoration``, ``header``, and ``footer`` elements.
  - Brought ``interpreted`` element in line with the parser: changed
    attribute "type" to "role", added "position".
  - Added support for generic bibliographic fields.

* spec/notes.txt: Continual updates.  Added "Project Policies".

* spec/pep-0256.txt:  Updated.  Added "Roadmap to the Doctring PEPs"
  section.

* spec/pep-0257.txt: Clarified prohibition of signature repetition.

* spec/pep-0258.txt: Updated.  Added text from pysource.txt and
  mailing list discussions.

* spec/pep-0287.txt:

  - Renamed to "reStructuredText Docstring Format".
  - Minor edits.
  - Reworked Q&A as an enumerated list.
  - Converted to reStructuredText format.

* spec/pysource.dtd:

  - Reworked structural elements, incorporating ideas from Tony Ibbs.

* spec/pysource.txt: Removed from project.  Moved much of its contents
  to pep-0258.txt.

* spec/rst/alternatives.txt:

  - Expanded auto-enumerated list idea; thanks to Fred Bremmer.
  - Added "Inline External Targets" section.

* spec/rst/directives.txt:

  - Added "backlinks" attribute to "contents" directive.

* spec/rst/problems.txt:

  - Updated the Enumerated List Markup discussion.
  - Added new alternative table markup syntaxes.

* spec/rst/reStructuredText.txt:

  - Clarified field list usage.
  - Updated enumerated list description.
  - Clarified purpose of directives.
  - Added ``-/:`` characters to inline markup's start string prefix,
    ``/`` to end string suffix.
  - Updated "Authors" bibliographic field behavior.
  - Changed "inline hyperlink targets" to "inline internal targets".
  - Added "simple table" syntax to supplement the existing but
    newly-renamed "grid tables".
  - Added cautions for anonymous hyperlink use.
  - Added "Dedication" and generic bibliographic fields.

* test: Made test modules standalone (subdirectories became packages).

* test/DocutilsTestSupport.py:

  - Added support for PEP extensions to reStructuredText.
  - Added support for simple tables.
  - Refactored naming.

* test/package_unittest.py: Renamed from UnitTestFolder.py.

  - Now supports true packages containing test modules
    (``__init__.py`` files required); fixes duplicate module name bug.

* test/test_pep/: Subpackage added to project; PEP testing.

* test/test_rst/test_SimpleTableParser.py: Added to project.

* tools:

  - Updated html.py and publish.py front-end tools to use the new
    command-line processing facilities of ``docutils.frontend``
    (exposed in ``docutils.core.Publisher``), reducing each to just a
    few lines of code.
  - Added ``locale.setlocale()`` calls to front-end tools.

* tools/buildhtml.py: Added to project; batch-generates .html from all
  the .txt files in directories and subdirectories.

* tools/default.css:

  - Added support for ``header`` and ``footer`` elements.
  - Added styles for "Dedication" topics (biblio fields).

* tools/docutils.conf: A configuration file; added to project.

* tools/docutils-xml.py: Added to project.

* tools/pep.py: Added to project; PEP to HTML front-end tool.

* tools/pep-html-template: Added to project.

* tools/pep2html.py: Added to project from Python (nondist/peps).
  Added support for Docutils (reStructuredText PEPs).

* tools/quicktest.py:

  - Added the ``--attributes`` option, hacked a bit.
  - Added a second command-line argument (output file); cleaned up.

* tools/stylesheets/: Subdirectory added to project.

* tools/stylesheets/pep.css: Added to project; stylesheet for PEPs.


Release 0.1 (2002-04-20)
========================

This is the first release of Docutils, merged from the now inactive
reStructuredText__ and `Docstring Processing System`__ projects.  For
the pre-Docutils history, see the `reStructuredText HISTORY`__ and the
`DPS HISTORY`__ files.

__ http://structuredtext.sourceforge.net/
__ http://docstring.sourceforge.net/
__ http://structuredtext.sourceforge.net/HISTORY.html
__ http://docstring.sourceforge.net/HISTORY.html

General changes: renamed 'dps' package to 'docutils'; renamed
'restructuredtext' subpackage to 'rst'; merged the codebases; merged
the test suites (reStructuredText's test/test_states renamed to
test/test_rst); and all modifications required to make it all work.

* docutils/parsers/rst/states.py:

  - Improved diagnostic system messages for missing blank lines.
  - Fixed substitution_reference bug.


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End:
��������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/core.py��������������������������������������������������0000644�0001750�0001750�00000053745�10322224711�022121� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Authors: David Goodger
# Contact: goodger@python.org
# Revision: $Revision: 2987 $
# Date: $Date: 2005-02-26 19:17:59 +0100 (Sat, 26 Feb 2005) $
# Copyright: This module has been placed in the public domain.

"""
Calling the ``publish_*`` convenience functions (or instantiating a
`Publisher` object) with component names will result in default
behavior.  For custom behavior (setting component options), create
custom component objects first, and pass *them* to
``publish_*``/`Publisher`.  See `The Docutils Publisher`_.

.. _The Docutils Publisher: http://docutils.sf.net/docs/api/publisher.html
"""

__docformat__ = 'reStructuredText'

import sys
import pprint
from docutils import __version__, SettingsSpec
from docutils import frontend, io, utils, readers, writers
from docutils.frontend import OptionParser


class Publisher:

    """
    A facade encapsulating the high-level logic of a Docutils system.
    """

    def __init__(self, reader=None, parser=None, writer=None,
                 source=None, source_class=io.FileInput,
                 destination=None, destination_class=io.FileOutput,
                 settings=None):
        """
        Initial setup.  If any of `reader`, `parser`, or `writer` are not
        specified, the corresponding ``set_...`` method should be called with
        a component name (`set_reader` sets the parser as well).
        """

        self.reader = reader
        """A `docutils.readers.Reader` instance."""

        self.parser = parser
        """A `docutils.parsers.Parser` instance."""

        self.writer = writer
        """A `docutils.writers.Writer` instance."""

        self.source = source
        """The source of input data, a `docutils.io.Input` instance."""

        self.source_class = source_class
        """The class for dynamically created source objects."""

        self.destination = destination
        """The destination for docutils output, a `docutils.io.Output`
        instance."""

        self.destination_class = destination_class
        """The class for dynamically created destination objects."""

        self.settings = settings
        """An object containing Docutils settings as instance attributes.
        Set by `self.process_command_line()` or `self.get_settings()`."""

    def set_reader(self, reader_name, parser, parser_name):
        """Set `self.reader` by name."""
        reader_class = readers.get_reader_class(reader_name)
        self.reader = reader_class(parser, parser_name)
        self.parser = self.reader.parser

    def set_writer(self, writer_name):
        """Set `self.writer` by name."""
        writer_class = writers.get_writer_class(writer_name)
        self.writer = writer_class()

    def set_components(self, reader_name, parser_name, writer_name):
        if self.reader is None:
            self.set_reader(reader_name, self.parser, parser_name)
        if self.parser is None:
            if self.reader.parser is None:
                self.reader.set_parser(parser_name)
            self.parser = self.reader.parser
        if self.writer is None:
            self.set_writer(writer_name)

    def setup_option_parser(self, usage=None, description=None,
                            settings_spec=None, config_section=None,
                            **defaults):
        if config_section:
            if not settings_spec:
                settings_spec = SettingsSpec()
            settings_spec.config_section = config_section
            parts = config_section.split()
            if len(parts) > 1 and parts[-1] == 'application':
                settings_spec.config_section_dependencies = ['applications']
        #@@@ Add self.source & self.destination to components in future?
        option_parser = OptionParser(
            components=(self.parser, self.reader, self.writer, settings_spec),
            defaults=defaults, read_config_files=1,
            usage=usage, description=description)
        return option_parser

    def get_settings(self, usage=None, description=None,
                     settings_spec=None, config_section=None, **defaults):
        """
        Set and return default settings (overrides in `defaults` dict).

        Set components first (`self.set_reader` & `self.set_writer`).
        Explicitly setting `self.settings` disables command line option
        processing from `self.publish()`.
        """
        option_parser = self.setup_option_parser(
            usage, description, settings_spec, config_section, **defaults)
        self.settings = option_parser.get_default_values()
        return self.settings

    def process_programmatic_settings(self, settings_spec,
                                      settings_overrides,
                                      config_section):
        if self.settings is None:
            defaults = (settings_overrides or {}).copy()
            # Propagate exceptions by default when used programmatically:
            defaults.setdefault('traceback', 1)
            self.get_settings(settings_spec=settings_spec,
                              config_section=config_section,
                              **defaults)

    def process_command_line(self, argv=None, usage=None, description=None,
                             settings_spec=None, config_section=None,
                             **defaults):
        """
        Pass an empty list to `argv` to avoid reading `sys.argv` (the
        default).

        Set components first (`self.set_reader` & `self.set_writer`).
        """
        option_parser = self.setup_option_parser(
            usage, description, settings_spec, config_section, **defaults)
        if argv is None:
            argv = sys.argv[1:]
        self.settings = option_parser.parse_args(argv)

    def set_io(self, source_path=None, destination_path=None):
        if self.source is None:
            self.set_source(source_path=source_path)
        if self.destination is None:
            self.set_destination(destination_path=destination_path)

    def set_source(self, source=None, source_path=None):
        if source_path is None:
            source_path = self.settings._source
        else:
            self.settings._source = source_path
        self.source = self.source_class(
            source=source, source_path=source_path,
            encoding=self.settings.input_encoding)

    def set_destination(self, destination=None, destination_path=None):
        if destination_path is None:
            destination_path = self.settings._destination
        else:
            self.settings._destination = destination_path
        self.destination = self.destination_class(
            destination=destination, destination_path=destination_path,
            encoding=self.settings.output_encoding,
            error_handler=self.settings.output_encoding_error_handler)

    def apply_transforms(self, document):
        document.transformer.populate_from_components(
            (self.source, self.reader, self.reader.parser, self.writer,
             self.destination))
        document.transformer.apply_transforms()

    def publish(self, argv=None, usage=None, description=None,
                settings_spec=None, settings_overrides=None,
                config_section=None, enable_exit_status=None):
        """
        Process command line options and arguments (if `self.settings` not
        already set), run `self.reader` and then `self.writer`.  Return
        `self.writer`'s output.
        """
        if self.settings is None:
            self.process_command_line(
                argv, usage, description, settings_spec, config_section,
                **(settings_overrides or {}))
        self.set_io()
        exit = None
        document = None
        try:
            document = self.reader.read(self.source, self.parser,
                                        self.settings)
            self.apply_transforms(document)
            output = self.writer.write(document, self.destination)
            self.writer.assemble_parts()
        except Exception, error:
            if self.settings.traceback: # propagate exceptions?
                self.debugging_dumps(document)                
                raise
            self.report_Exception(error)
            exit = 1
        self.debugging_dumps(document)
        if (enable_exit_status and document
            and (document.reporter.max_level
                 >= self.settings.exit_status_level)):
            sys.exit(document.reporter.max_level + 10)
        elif exit:
            sys.exit(1)
        return output

    def debugging_dumps(self, document):
        if not document:
            return
        if self.settings.dump_settings:
            print >>sys.stderr, '\n::: Runtime settings:'
            print >>sys.stderr, pprint.pformat(self.settings.__dict__)
        if self.settings.dump_internals and document:
            print >>sys.stderr, '\n::: Document internals:'
            print >>sys.stderr, pprint.pformat(document.__dict__)
        if self.settings.dump_transforms and document:
            print >>sys.stderr, '\n::: Transforms applied:'
            print >>sys.stderr, pprint.pformat(document.transformer.applied)
        if self.settings.dump_pseudo_xml and document:
            print >>sys.stderr, '\n::: Pseudo-XML:'
            print >>sys.stderr, document.pformat().encode(
                'raw_unicode_escape')

    def report_Exception(self, error):
        if isinstance(error, utils.SystemMessage):
            self.report_SystemMessage(error)
        elif isinstance(error, UnicodeError):
            self.report_UnicodeError(error)
        else:
            print >>sys.stderr, '%s: %s' % (error.__class__.__name__, error)
            print >>sys.stderr, ("""\
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to <docutils-users@lists.sf.net>.
Include "--traceback" output, Docutils version (%s),
Python version (%s), your OS type & version, and the
command line used.""" % (__version__, sys.version.split()[0]))

    def report_SystemMessage(self, error):
        print >>sys.stderr, ('Exiting due to level-%s (%s) system message.'
                             % (error.level,
                                utils.Reporter.levels[error.level]))

    def report_UnicodeError(self, error):
        sys.stderr.write(
            '%s: %s\n'
            '\n'
            'The specified output encoding (%s) cannot\n'
            'handle all of the output.\n'
            'Try setting "--output-encoding-error-handler" to\n'
            '\n'
            '* "xmlcharrefreplace" (for HTML & XML output);\n'
            % (error.__class__.__name__, error,
               self.settings.output_encoding))
        try:
            data = error.object[error.start:error.end]
            sys.stderr.write(
                '  the output will contain "%s" and should be usable.\n'
                '* "backslashreplace" (for other output formats, Python 2.3+);\n'
                '  look for "%s" in the output.\n'
                % (data.encode('ascii', 'xmlcharrefreplace'),
                   data.encode('ascii', 'backslashreplace')))
        except AttributeError:
            sys.stderr.write('  the output should be usable as-is.\n')
        sys.stderr.write(
            '* "replace"; look for "?" in the output.\n'
            '\n'
            '"--output-encoding-error-handler" is currently set to "%s".\n'
            '\n'
            'Exiting due to error.  Use "--traceback" to diagnose.\n'
            'If the advice above doesn\'t eliminate the error,\n'
            'please report it to <docutils-users@lists.sf.net>.\n'
            'Include "--traceback" output, Docutils version (%s),\n'
            'Python version (%s), your OS type & version, and the\n'
            'command line used.\n'
            % (self.settings.output_encoding_error_handler,
               __version__, sys.version.split()[0]))

default_usage = '%prog [options] [<source> [<destination>]]'
default_description = ('Reads from <source> (default is stdin) and writes to '
                       '<destination> (default is stdout).')

def publish_cmdline(reader=None, reader_name='standalone',
                    parser=None, parser_name='restructuredtext',
                    writer=None, writer_name='pseudoxml',
                    settings=None, settings_spec=None,
                    settings_overrides=None, config_section=None,
                    enable_exit_status=1, argv=None,
                    usage=default_usage, description=default_description):
    """
    Set up & run a `Publisher` for command-line-based file I/O (input and
    output file paths taken automatically from the command line).  Return the
    encoded string output also.

    Parameters: see `publish_programmatically` for the remainder.

    - `argv`: Command-line argument list to use instead of ``sys.argv[1:]``.
    - `usage`: Usage string, output if there's a problem parsing the command
      line.
    - `description`: Program description, output for the "--help" option
      (along with command-line option descriptions).
    """
    pub = Publisher(reader, parser, writer, settings=settings)
    pub.set_components(reader_name, parser_name, writer_name)
    output = pub.publish(
        argv, usage, description, settings_spec, settings_overrides,
        config_section=config_section, enable_exit_status=enable_exit_status)
    return output

def publish_file(source=None, source_path=None,
                 destination=None, destination_path=None,
                 reader=None, reader_name='standalone',
                 parser=None, parser_name='restructuredtext',
                 writer=None, writer_name='pseudoxml',
                 settings=None, settings_spec=None, settings_overrides=None,
                 config_section=None, enable_exit_status=None):
    """
    Set up & run a `Publisher` for programmatic use with file-like I/O.
    Return the encoded string output also.

    Parameters: see `publish_programmatically`.
    """
    output, pub = publish_programmatically(
        source_class=io.FileInput, source=source, source_path=source_path,
        destination_class=io.FileOutput,
        destination=destination, destination_path=destination_path,
        reader=reader, reader_name=reader_name,
        parser=parser, parser_name=parser_name,
        writer=writer, writer_name=writer_name,
        settings=settings, settings_spec=settings_spec,
        settings_overrides=settings_overrides,
        config_section=config_section,
        enable_exit_status=enable_exit_status)
    return output

def publish_string(source, source_path=None, destination_path=None,
                   reader=None, reader_name='standalone',
                   parser=None, parser_name='restructuredtext',
                   writer=None, writer_name='pseudoxml',
                   settings=None, settings_spec=None,
                   settings_overrides=None, config_section=None,
                   enable_exit_status=None):
    """
    Set up & run a `Publisher` for programmatic use with string I/O.  Return
    the encoded string or Unicode string output.

    For encoded string output, be sure to set the 'output_encoding' setting to
    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
    output.  Here's one way::

        publish_string(..., settings_overrides={'output_encoding': 'unicode'})

    Similarly for Unicode string input (`source`)::

        publish_string(..., settings_overrides={'input_encoding': 'unicode'})

    Parameters: see `publish_programmatically`.
    """
    output, pub = publish_programmatically(
        source_class=io.StringInput, source=source, source_path=source_path,
        destination_class=io.StringOutput,
        destination=None, destination_path=destination_path,
        reader=reader, reader_name=reader_name,
        parser=parser, parser_name=parser_name,
        writer=writer, writer_name=writer_name,
        settings=settings, settings_spec=settings_spec,
        settings_overrides=settings_overrides,
        config_section=config_section,
        enable_exit_status=enable_exit_status)
    return output

def publish_parts(source, source_path=None, destination_path=None,
                  reader=None, reader_name='standalone',
                  parser=None, parser_name='restructuredtext',
                  writer=None, writer_name='pseudoxml',
                  settings=None, settings_spec=None,
                  settings_overrides=None, config_section=None,
                  enable_exit_status=None):
    """
    Set up & run a `Publisher`, and return a dictionary of document parts.
    Dictionary keys are the names of parts, and values are Unicode strings;
    encoding is up to the client.  For programmatic use with string I/O.

    For encoded string input, be sure to set the 'input_encoding' setting to
    the desired encoding.  Set it to 'unicode' for unencoded Unicode string
    input.  Here's how::

        publish_string(..., settings_overrides={'input_encoding': 'unicode'})

    Parameters: see `publish_programmatically`.
    """
    output, pub = publish_programmatically(
        source_class=io.StringInput, source=source, source_path=source_path,
        destination_class=io.StringOutput,
        destination=None, destination_path=destination_path,
        reader=reader, reader_name=reader_name,
        parser=parser, parser_name=parser_name,
        writer=writer, writer_name=writer_name,
        settings=settings, settings_spec=settings_spec,
        settings_overrides=settings_overrides,
        config_section=config_section,
        enable_exit_status=enable_exit_status)
    return pub.writer.parts

def publish_programmatically(source_class, source, source_path,
                            destination_class, destination, destination_path,
                            reader, reader_name,
                            parser, parser_name,
                            writer, writer_name,
                            settings, settings_spec,
                            settings_overrides, config_section,
                            enable_exit_status):
    """
    Set up & run a `Publisher` for custom programmatic use.  Return the
    encoded string output and the Publisher object.

    Applications should not need to call this function directly.  If it does
    seem to be necessary to call this function directly, please write to the
    docutils-develop@lists.sourceforge.net mailing list.

    Parameters:

    * `source_class` **required**: The class for dynamically created source
      objects.  Typically `io.FileInput` or `io.StringInput`.

    * `source`: Type depends on `source_class`:

      - `io.FileInput`: Either a file-like object (must have 'read' and
        'close' methods), or ``None`` (`source_path` is opened).  If neither
        `source` nor `source_path` are supplied, `sys.stdin` is used.

      - `io.StringInput` **required**: The input string, either an encoded
        8-bit string (set the 'input_encoding' setting to the correct
        encoding) or a Unicode string (set the 'input_encoding' setting to
        'unicode').

    * `source_path`: Type depends on `source_class`:

      - `io.FileInput`: Path to the input file, opened if no `source`
        supplied.

      - `io.StringInput`: Optional.  Path to the file or object that produced
        `source`.  Only used for diagnostic output.

    * `destination_class` **required**: The class for dynamically created
      destination objects.  Typically `io.FileOutput` or `io.StringOutput`.

    * `destination`: Type depends on `destination_class`:

      - `io.FileOutput`: Either a file-like object (must have 'write' and
        'close' methods), or ``None`` (`destination_path` is opened).  If
        neither `destination` nor `destination_path` are supplied,
        `sys.stdout` is used.

      - `io.StringOutput`: Not used; pass ``None``.

    * `destination_path`: Type depends on `destination_class`:

      - `io.FileOutput`: Path to the output file.  Opened if no `destination`
        supplied.

      - `io.StringOutput`: Path to the file or object which will receive the
        output; optional.  Used for determining relative paths (stylesheets,
        source links, etc.).

    * `reader`: A `docutils.readers.Reader` object.

    * `reader_name`: Name or alias of the Reader class to be instantiated if
      no `reader` supplied.

    * `parser`: A `docutils.parsers.Parser` object.

    * `parser_name`: Name or alias of the Parser class to be instantiated if
      no `parser` supplied.

    * `writer`: A `docutils.writers.Writer` object.

    * `writer_name`: Name or alias of the Writer class to be instantiated if
      no `writer` supplied.

    * `settings`: A runtime settings (`docutils.frontend.Values`) object, for
      dotted-attribute access to runtime settings.  It's the end result of the
      `SettingsSpec`, config file, and option processing.  If `settings` is
      passed, it's assumed to be complete and no further setting/config/option
      processing is done.

    * `settings_spec`: A `docutils.SettingsSpec` subclass or object.  Provides
      extra application-specific settings definitions independently of
      components.  In other words, the application becomes a component, and
      its settings data is processed along with that of the other components.
      Used only if no `settings` specified.

    * `settings_overrides`: A dictionary containing application-specific
      settings defaults that override the defaults of other components.
      Used only if no `settings` specified.

    * `config_section`: A string, the name of the configuration file section
      for this application.  Overrides the ``config_section`` attribute
      defined by `settings_spec`.  Used only if no `settings` specified.

    * `enable_exit_status`: Boolean; enable exit status at end of processing?
    """
    pub = Publisher(reader, parser, writer, settings=settings,
                    source_class=source_class,
                    destination_class=destination_class)
    pub.set_components(reader_name, parser_name, writer_name)
    pub.process_programmatic_settings(
        settings_spec, settings_overrides, config_section)
    pub.set_source(source, source_path)
    pub.set_destination(destination, destination_path)
    output = pub.publish(enable_exit_status=enable_exit_status)
    return output, pub
���������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/�������������������������������������������������0000755�0001750�0001750�00000000000�10447233610�022234� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/python/������������������������������������������0000755�0001750�0001750�00000000000�10447233610�023555� 5����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/python/moduleparser.py���������������������������0000644�0001750�0001750�00000062356�10322224711�026637� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 2449 $
# Date: $Date: 2004-07-25 03:45:27 +0200 (Sun, 25 Jul 2004) $
# Copyright: This module has been placed in the public domain.

"""
Parser for Python modules.  Requires Python 2.2 or higher.

The `parse_module()` function takes a module's text and file name,
runs it through the module parser (using compiler.py and tokenize.py)
and produces a parse tree of the source code, using the nodes as found
in pynodes.py.  For example, given this module (x.py)::

    # comment

    '''Docstring'''

    '''Additional docstring'''

    __docformat__ = 'reStructuredText'

    a = 1
    '''Attribute docstring'''

    class C(Super):

        '''C's docstring'''

        class_attribute = 1
        '''class_attribute's docstring'''

        def __init__(self, text=None):
            '''__init__'s docstring'''

            self.instance_attribute = (text * 7
                                       + ' whaddyaknow')
            '''instance_attribute's docstring'''


    def f(x,                            # parameter x
          y=a*5,                        # parameter y
          *args):                       # parameter args
        '''f's docstring'''
        return [x + item for item in args]

    f.function_attribute = 1
    '''f.function_attribute's docstring'''

The module parser will produce this module documentation tree::

    <module_section filename="test data">
        <docstring>
            Docstring
        <docstring lineno="5">
            Additional docstring
        <attribute lineno="7">
	    <object_name>
	        __docformat__
            <expression_value lineno="7">
                'reStructuredText'
        <attribute lineno="9">
	    <object_name>
	        a
            <expression_value lineno="9">
                1
            <docstring lineno="10">
                Attribute docstring
        <class_section lineno="12">
	    <object_name>
	        C
            <class_base>
	        Super
            <docstring lineno="12">
                C's docstring
            <attribute lineno="16">
	        <object_name>
		    class_attribute
                <expression_value lineno="16">
                    1
                <docstring lineno="17">
                    class_attribute's docstring
            <method_section lineno="19">
	        <object_name>
		    __init__
                <docstring lineno="19">
                    __init__'s docstring
                <parameter_list lineno="19">
                    <parameter lineno="19">
		        <object_name>
			    self
                    <parameter lineno="19">
		        <object_name>
			    text
                        <parameter_default lineno="19">
                            None
                <attribute lineno="22">
		    <object_name>
		        self.instance_attribute
                    <expression_value lineno="22">
                        (text * 7 + ' whaddyaknow')
                    <docstring lineno="24">
                        instance_attribute's docstring
        <function_section lineno="27">
	    <object_name>
	        f
            <docstring lineno="27">
                f's docstring
            <parameter_list lineno="27">
                <parameter lineno="27">
		    <object_name>
		        x
                    <comment>
                        # parameter x
                <parameter lineno="27">
		    <object_name>
		        y
                    <parameter_default lineno="27">
                        a * 5
                    <comment>
                        # parameter y
                <parameter excess_positional="1" lineno="27">
		    <object_name>
		        args
                    <comment>
                        # parameter args
        <attribute lineno="33">
	    <object_name>
	        f.function_attribute
            <expression_value lineno="33">
                1
            <docstring lineno="34">
                f.function_attribute's docstring

(Comments are not implemented yet.)

compiler.parse() provides most of what's needed for this doctree, and
"tokenize" can be used to get the rest.  We can determine the line
number from the compiler.parse() AST, and the TokenParser.rhs(lineno)
method provides the rest.

The Docutils Python reader component will transform this module doctree into a
Python-specific Docutils doctree, and then a `stylist transform`_ will
further transform it into a generic doctree.  Namespaces will have to be
compiled for each of the scopes, but I'm not certain at what stage of
processing.

It's very important to keep all docstring processing out of this, so that it's
a completely generic and not tool-specific.

> Why perform all of those transformations?  Why not go from the AST to a
> generic doctree?  Or, even from the AST to the final output?

I want the docutils.readers.python.moduleparser.parse_module() function to
produce a standard documentation-oriented tree that can be used by any tool.
We can develop it together without having to compromise on the rest of our
design (i.e., HappyDoc doesn't have to be made to work like Docutils, and
vice-versa).  It would be a higher-level version of what compiler.py provides.

The Python reader component transforms this generic AST into a Python-specific
doctree (it knows about modules, classes, functions, etc.), but this is
specific to Docutils and cannot be used by HappyDoc or others.  The stylist
transform does the final layout, converting Python-specific structures
("class" sections, etc.) into a generic doctree using primitives (tables,
sections, lists, etc.).  This generic doctree does *not* know about Python
structures any more.  The advantage is that this doctree can be handed off to
any of the output writers to create any output format we like.

The latter two transforms are separate because I want to be able to have
multiple independent layout styles (multiple runtime-selectable "stylist
transforms").  Each of the existing tools (HappyDoc, pydoc, epydoc, Crystal,
etc.) has its own fixed format.  I personally don't like the tables-based
format produced by these tools, and I'd like to be able to customize the
format easily.  That's the goal of stylist transforms, which are independent
from the Reader component itself.  One stylist transform could produce
HappyDoc-like output, another could produce output similar to module docs in
the Python library reference manual, and so on.

It's for exactly this reason:

>> It's very important to keep all docstring processing out of this, so that
>> it's a completely generic and not tool-specific.

... but it goes past docstring processing.  It's also important to keep style
decisions and tool-specific data transforms out of this module parser.


Issues
======

* At what point should namespaces be computed?  Should they be part of the
  basic AST produced by the ASTVisitor walk, or generated by another tree
  traversal?

* At what point should a distinction be made between local variables &
  instance attributes in __init__ methods?

* Docstrings are getting their lineno from their parents.  Should the
  TokenParser find the real line no's?

* Comments: include them?  How and when?  Only full-line comments, or
  parameter comments too?  (See function "f" above for an example.)

* Module could use more docstrings & refactoring in places.

"""

__docformat__ = 'reStructuredText'

import sys
import compiler
import compiler.ast
import tokenize
import token
from compiler.consts import OP_ASSIGN
from compiler.visitor import ASTVisitor
from types import StringType, UnicodeType, TupleType
from docutils.readers.python import pynodes
from docutils.nodes import Text


def parse_module(module_text, filename):
    """Return a module documentation tree from `module_text`."""
    ast = compiler.parse(module_text)
    token_parser = TokenParser(module_text)
    visitor = ModuleVisitor(filename, token_parser)
    compiler.walk(ast, visitor, walker=visitor)
    return visitor.module

class BaseVisitor(ASTVisitor):

    def __init__(self, token_parser):
        ASTVisitor.__init__(self)
        self.token_parser = token_parser
        self.context = []
        self.documentable = None

    def default(self, node, *args):
        self.documentable = None
        #print 'in default (%s)' % node.__class__.__name__
        #ASTVisitor.default(self, node, *args)

    def default_visit(self, node, *args):
        #print 'in default_visit (%s)' % node.__class__.__name__
        ASTVisitor.default(self, node, *args)


class DocstringVisitor(BaseVisitor):

    def visitDiscard(self, node):
        if self.documentable:
            self.visit(node.expr)

    def visitConst(self, node):
        if self.documentable:
            if type(node.value) in (StringType, UnicodeType):
                self.documentable.append(make_docstring(node.value, node.lineno))
            else:
                self.documentable = None

    def visitStmt(self, node):
        self.default_visit(node)


class AssignmentVisitor(DocstringVisitor):

    def visitAssign(self, node):
        visitor = AttributeVisitor(self.token_parser)
        compiler.walk(node, visitor, walker=visitor)
        if visitor.attributes:
            self.context[-1].extend(visitor.attributes)
        if len(visitor.attributes) == 1:
            self.documentable = visitor.attributes[0]
        else:
            self.documentable = None


class ModuleVisitor(AssignmentVisitor):

    def __init__(self, filename, token_parser):
        AssignmentVisitor.__init__(self, token_parser)
        self.filename = filename
        self.module = None

    def visitModule(self, node):
        self.module = module = pynodes.module_section()
        module['filename'] = self.filename
        append_docstring(module, node.doc, node.lineno)
        self.context.append(module)
        self.documentable = module
        self.visit(node.node)
        self.context.pop()

    def visitImport(self, node):
        self.context[-1] += make_import_group(names=node.names,
                                              lineno=node.lineno)
        self.documentable = None

    def visitFrom(self, node):
        self.context[-1].append(
            make_import_group(names=node.names, from_name=node.modname,
                              lineno=node.lineno))
        self.documentable = None

    def visitFunction(self, node):
        visitor = FunctionVisitor(self.token_parser,
                                  function_class=pynodes.function_section)
        compiler.walk(node, visitor, walker=visitor)
        self.context[-1].append(visitor.function)

    def visitClass(self, node):
        visitor = ClassVisitor(self.token_parser)
        compiler.walk(node, visitor, walker=visitor)
        self.context[-1].append(visitor.klass)


class AttributeVisitor(BaseVisitor):

    def __init__(self, token_parser):
        BaseVisitor.__init__(self, token_parser)
        self.attributes = pynodes.class_attribute_section()

    def visitAssign(self, node):
        # Don't visit the expression itself, just the attribute nodes:
        for child in node.nodes:
            self.dispatch(child)
        expression_text = self.token_parser.rhs(node.lineno)
        expression = pynodes.expression_value()
        expression.append(Text(expression_text))
        for attribute in self.attributes:
            attribute.append(expression)

    def visitAssName(self, node):
        self.attributes.append(make_attribute(node.name,
                                              lineno=node.lineno))

    def visitAssTuple(self, node):
        attributes = self.attributes
        self.attributes = []
        self.default_visit(node)
        n = pynodes.attribute_tuple()
        n.extend(self.attributes)
        n['lineno'] = self.attributes[0]['lineno']
        attributes.append(n)
        self.attributes = attributes
        #self.attributes.append(att_tuple)

    def visitAssAttr(self, node):
        self.default_visit(node, node.attrname)

    def visitGetattr(self, node, suffix):
        self.default_visit(node, node.attrname + '.' + suffix)

    def visitName(self, node, suffix):
        self.attributes.append(make_attribute(node.name + '.' + suffix,
                                              lineno=node.lineno))


class FunctionVisitor(DocstringVisitor):

    in_function = 0

    def __init__(self, token_parser, function_class):
        DocstringVisitor.__init__(self, token_parser)
        self.function_class = function_class

    def visitFunction(self, node):
        if self.in_function:
            self.documentable = None
            # Don't bother with nested function definitions.
            return
        self.in_function = 1
        self.function = function = make_function_like_section(
            name=node.name,
            lineno=node.lineno,
            doc=node.doc,
            function_class=self.function_class)
        self.context.append(function)
        self.documentable = function
        self.parse_parameter_list(node)
        self.visit(node.code)
        self.context.pop()

    def parse_parameter_list(self, node):
        parameters = []
        special = []
        argnames = list(node.argnames)
        if node.kwargs:
            special.append(make_parameter(argnames[-1], excess_keyword=1))
            argnames.pop()
        if node.varargs:
            special.append(make_parameter(argnames[-1],
                                          excess_positional=1))
            argnames.pop()
        defaults = list(node.defaults)
        defaults = [None] * (len(argnames) - len(defaults)) + defaults
        function_parameters = self.token_parser.function_parameters(
            node.lineno)
        #print >>sys.stderr, function_parameters
        for argname, default in zip(argnames, defaults):
            if type(argname) is TupleType:
                parameter = pynodes.parameter_tuple()
                for tuplearg in argname:
                    parameter.append(make_parameter(tuplearg))
                argname = normalize_parameter_name(argname)
            else:
                parameter = make_parameter(argname)
            if default:
                n_default = pynodes.parameter_default()
                n_default.append(Text(function_parameters[argname]))
                parameter.append(n_default)
            parameters.append(parameter)
        if parameters or special:
            special.reverse()
            parameters.extend(special)
            parameter_list = pynodes.parameter_list()
            parameter_list.extend(parameters)
            self.function.append(parameter_list)


class ClassVisitor(AssignmentVisitor):

    in_class = 0

    def __init__(self, token_parser):
        AssignmentVisitor.__init__(self, token_parser)
        self.bases = []

    def visitClass(self, node):
        if self.in_class:
            self.documentable = None
            # Don't bother with nested class definitions.
            return
        self.in_class = 1
        #import mypdb as pdb
        #pdb.set_trace()
        for base in node.bases:
            self.visit(base)
        self.klass = klass = make_class_section(node.name, self.bases,
                                                doc=node.doc,
                                                lineno=node.lineno)
        self.context.append(klass)
        self.documentable = klass
        self.visit(node.code)
        self.context.pop()

    def visitGetattr(self, node, suffix=None):
        if suffix:
            name = node.attrname + '.' + suffix
        else:
            name = node.attrname
        self.default_visit(node, name)

    def visitName(self, node, suffix=None):
        if suffix:
            name = node.name + '.' + suffix
        else:
            name = node.name
        self.bases.append(name)

    def visitFunction(self, node):
        if node.name == '__init__':
            visitor = InitMethodVisitor(self.token_parser,
                                        function_class=pynodes.method_section)
            compiler.walk(node, visitor, walker=visitor)
        else:
            visitor = FunctionVisitor(self.token_parser,
                                      function_class=pynodes.method_section)
            compiler.walk(node, visitor, walker=visitor)
        self.context[-1].append(visitor.function)


class InitMethodVisitor(FunctionVisitor, AssignmentVisitor): pass


class TokenParser:

    def __init__(self, text):
        self.text = text + '\n\n'
        self.lines = self.text.splitlines(1)
        self.generator = tokenize.generate_tokens(iter(self.lines).next)
        self.next()

    def __iter__(self):
        return self

    def next(self):
        self.token = self.generator.next()
        self.type, self.string, self.start, self.end, self.line = self.token
        return self.token

    def goto_line(self, lineno):
        while self.start[0] < lineno:
            self.next()
        return token

    def rhs(self, lineno):
        """
        Return a whitespace-normalized expression string from the right-hand
        side of an assignment at line `lineno`.
        """
        self.goto_line(lineno)
        while self.string != '=':
            self.next()
        self.stack = None
        while self.type != token.NEWLINE and self.string != ';':
            if self.string == '=' and not self.stack:
                self.tokens = []
                self.stack = []
                self._type = None
                self._string = None
                self._backquote = 0
            else:
                self.note_token()
            self.next()
        self.next()
        text = ''.join(self.tokens)
        return text.strip()

    closers = {')': '(', ']': '[', '}': '{'}
    openers = {'(': 1, '[': 1, '{': 1}
    del_ws_prefix = {'.': 1, '=': 1, ')': 1, ']': 1, '}': 1, ':': 1, ',': 1}
    no_ws_suffix = {'.': 1, '=': 1, '(': 1, '[': 1, '{': 1}

    def note_token(self):
        if self.type == tokenize.NL:
            return
        del_ws = self.del_ws_prefix.has_key(self.string)
        append_ws = not self.no_ws_suffix.has_key(self.string)
        if self.openers.has_key(self.string):
            self.stack.append(self.string)
            if (self._type == token.NAME
                or self.closers.has_key(self._string)):
                del_ws = 1
        elif self.closers.has_key(self.string):
            assert self.stack[-1] == self.closers[self.string]
            self.stack.pop()
        elif self.string == '`':
            if self._backquote:
                del_ws = 1
                assert self.stack[-1] == '`'
                self.stack.pop()
            else:
                append_ws = 0
                self.stack.append('`')
            self._backquote = not self._backquote
        if del_ws and self.tokens and self.tokens[-1] == ' ':
            del self.tokens[-1]
        self.tokens.append(self.string)
        self._type = self.type
        self._string = self.string
        if append_ws:
            self.tokens.append(' ')

    def function_parameters(self, lineno):
        """
        Return a dictionary mapping parameters to defaults
        (whitespace-normalized strings).
        """
        self.goto_line(lineno)
        while self.string != 'def':
            self.next()
        while self.string != '(':
            self.next()
        name = None
        default = None
        parameter_tuple = None
        self.tokens = []
        parameters = {}
        self.stack = [self.string]
        self.next()
        while 1:
            if len(self.stack) == 1:
                if parameter_tuple:
                    # Just encountered ")".
                    #print >>sys.stderr, 'parameter_tuple: %r' % self.tokens
                    name = ''.join(self.tokens).strip()
                    self.tokens = []
                    parameter_tuple = None
                if self.string in (')', ','):
                    if name:
                        if self.tokens:
                            default_text = ''.join(self.tokens).strip()
                        else:
                            default_text = None
                        parameters[name] = default_text
                        self.tokens = []
                        name = None
                        default = None
                    if self.string == ')':
                        break
                elif self.type == token.NAME:
                    if name and default:
                        self.note_token()
                    else:
                        assert name is None, (
                            'token=%r name=%r parameters=%r stack=%r'
                            % (self.token, name, parameters, self.stack))
                        name = self.string
                        #print >>sys.stderr, 'name=%r' % name
                elif self.string == '=':
                    assert name is not None, 'token=%r' % (self.token,)
                    assert default is None, 'token=%r' % (self.token,)
                    assert self.tokens == [], 'token=%r' % (self.token,)
                    default = 1
                    self._type = None
                    self._string = None
                    self._backquote = 0
                elif name:
                    self.note_token()
                elif self.string == '(':
                    parameter_tuple = 1
                    self._type = None
                    self._string = None
                    self._backquote = 0
                    self.note_token()
                else:                   # ignore these tokens:
                    assert (self.string in ('*', '**', '\n') 
                            or self.type == tokenize.COMMENT), (
                        'token=%r' % (self.token,))
            else:
                self.note_token()
            self.next()
        return parameters


def make_docstring(doc, lineno):
    n = pynodes.docstring()
    if lineno:
        # Really, only module docstrings don't have a line
        # (@@: but maybe they should)
        n['lineno'] = lineno
    n.append(Text(doc))
    return n

def append_docstring(node, doc, lineno):
    if doc:
        node.append(make_docstring(doc, lineno))

def make_class_section(name, bases, lineno, doc):
    n = pynodes.class_section()
    n['lineno'] = lineno
    n.append(make_object_name(name))
    for base in bases:
        b = pynodes.class_base()
        b.append(make_object_name(base))
        n.append(b)
    append_docstring(n, doc, lineno)
    return n

def make_object_name(name):
    n = pynodes.object_name()
    n.append(Text(name))
    return n

def make_function_like_section(name, lineno, doc, function_class):
    n = function_class()
    n['lineno'] = lineno
    n.append(make_object_name(name))
    append_docstring(n, doc, lineno)
    return n

def make_import_group(names, lineno, from_name=None):
    n = pynodes.import_group()
    n['lineno'] = lineno
    if from_name:
        n_from = pynodes.import_from()
        n_from.append(Text(from_name))
        n.append(n_from)
    for name, alias in names:
        n_name = pynodes.import_name()
        n_name.append(Text(name))
        if alias:
            n_alias = pynodes.import_alias()
            n_alias.append(Text(alias))
            n_name.append(n_alias)
        n.append(n_name)
    return n

def make_class_attribute(name, lineno):
    n = pynodes.class_attribute()
    n['lineno'] = lineno
    n.append(Text(name))
    return n

def make_attribute(name, lineno):
    n = pynodes.attribute()
    n['lineno'] = lineno
    n.append(make_object_name(name))
    return n

def make_parameter(name, excess_keyword=0, excess_positional=0):
    """
    excess_keyword and excess_positional must be either 1 or 0, and
    not both of them can be 1.
    """
    n = pynodes.parameter()
    n.append(make_object_name(name))
    assert not excess_keyword or not excess_positional
    if excess_keyword:
        n['excess_keyword'] = 1
    if excess_positional:
        n['excess_positional'] = 1
    return n

def trim_docstring(text):
    """
    Trim indentation and blank lines from docstring text & return it.

    See PEP 257.
    """
    if not text:
        return text
    # Convert tabs to spaces (following the normal Python rules)
    # and split into a list of lines:
    lines = text.expandtabs().splitlines()
    # Determine minimum indentation (first line doesn't count):
    indent = sys.maxint
    for line in lines[1:]:
        stripped = line.lstrip()
        if stripped:
            indent = min(indent, len(line) - len(stripped))
    # Remove indentation (first line is special):
    trimmed = [lines[0].strip()]
    if indent < sys.maxint:
        for line in lines[1:]:
            trimmed.append(line[indent:].rstrip())
    # Strip off trailing and leading blank lines:
    while trimmed and not trimmed[-1]:
        trimmed.pop()
    while trimmed and not trimmed[0]:
        trimmed.pop(0)
    # Return a single string:
    return '\n'.join(trimmed)

def normalize_parameter_name(name):
    """
    Converts a tuple like ``('a', ('b', 'c'), 'd')`` into ``'(a, (b, c), d)'``
    """
    if type(name) is TupleType:
        return '(%s)' % ', '.join([normalize_parameter_name(n) for n in name])
    else:
        return name

if __name__ == '__main__':
    import sys
    args = sys.argv[1:]
    if args[0] == '-v':
        filename = args[1]
        module_text = open(filename).read()
        ast = compiler.parse(module_text)
        visitor = compiler.visitor.ExampleASTVisitor()
        compiler.walk(ast, visitor, walker=visitor, verbose=1)
    else:
        filename = args[0]
        content = open(filename).read()
        print parse_module(content, filename).pformat()

����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/python/__init__.py�������������������������������0000644�0001750�0001750�00000010627�10322224711�025666� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3038 $
# Date: $Date: 2005-03-14 17:16:57 +0100 (Mon, 14 Mar 2005) $
# Copyright: This module has been placed in the public domain.

"""
This package contains the Python Source Reader modules.

It requires Python 2.2 or higher (`moduleparser` depends on the
`compiler` and `tokenize` modules).
"""

__docformat__ = 'reStructuredText'


import sys
import docutils.readers
from docutils.readers.python import moduleparser
from docutils import parsers
from docutils import nodes
from docutils.readers.python import pynodes
from docutils import readers

class Reader(docutils.readers.Reader):

    config_section = 'python reader'
    config_section_dependencies = ('readers',)

    default_parser = 'restructuredtext'

    def parse(self):
        """Parse `self.input` into a document tree."""
        self.document = document = self.new_document()
        module_section = moduleparser.parse_module(self.input,
                                                   self.source.source_path)
        module_section.walk(DocformatVisitor(self.document))
        visitor = DocstringFormattingVisitor(
            document=document,
            default_parser=self.default_parser)
        module_section.walk(visitor)
        self.document.append(module_section)


class DocformatVisitor(nodes.SparseNodeVisitor):

    """
    This sets docformat attributes in a module.  Wherever an assignment
    to __docformat__ is found, we look for the enclosing scope -- a class,
    a module, or a function -- and set the docformat attribute there.

    We can't do this during the DocstringFormattingVisitor walking,
    because __docformat__ may appear below a docstring in that format
    (typically below the module docstring).
    """

    def visit_attribute(self, node):
        assert isinstance(node[0], pynodes.object_name)
        name = node[0][0].data
        if name != '__docformat__':
            return
        value = None
        for child in children:
            if isinstance(child, pynodes.expression_value):
                value = child[0].data
                break
        assert value.startswith("'") or value.startswith('"'), "__docformat__ must be assigned a string literal (not %s); line: %s" % (value, node['lineno'])
        name = name[1:-1]
        looking_in = node.parent
        while not isinstance(looking_in, (pynodes.module_section,
                                          pynodes.function_section,
                                          pynodes.class_section)):
            looking_in = looking_in.parent
        looking_in['docformat'] = name


class DocstringFormattingVisitor(nodes.SparseNodeVisitor):

    def __init__(self, document, default_parser):
        self.document = document
        self.default_parser = default_parser
        self.parsers = {}

    def visit_docstring(self, node):
        text = node[0].data
        docformat = self.find_docformat(node)
        del node[0]
        node['docformat'] = docformat
        parser = self.get_parser(docformat)
        parser.parse(text, self.document)
        for child in self.document.children:
            node.append(child)
        self.document.current_source = self.document.current_line = None
        del self.document[:]

    def get_parser(self, parser_name):
        """
        Get a parser based on its name.  We reuse parsers during this
        visitation, so parser instances are cached.
        """
        parser_name = parsers._parser_aliases.get(parser_name, parser_name)
        if not self.parsers.has_key(parser_name):
            cls = parsers.get_parser_class(parser_name)
            self.parsers[parser_name] = cls()
        return self.parsers[parser_name]

    def find_docformat(self, node):
        """
        Find the __docformat__ closest to this node (i.e., look in the
        class or module)
        """
        while node:
            if node.get('docformat'):
                return node['docformat']
            node = node.parent
        return self.default_parser


if __name__ == '__main__':
    try:
        import locale
        locale.setlocale(locale.LC_ALL, '')
    except:
        pass

    from docutils.core import publish_cmdline, default_description

    description = ('Generates pseudo-XML from Python modules '
                   '(for testing purposes).  ' + default_description)

    publish_cmdline(description=description,
                    reader=Reader())
���������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/python/pynodes.py��������������������������������0000644�0001750�0001750�00000006171�10322224711�025607� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������#! /usr/bin/env python

"""
:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Revision: $Revision: 1881 $
:Date: $Date: 2004-03-24 00:21:11 +0100 (Wed, 24 Mar 2004) $
:Copyright: This module has been placed in the public domain.

"""

from docutils import nodes
from docutils.nodes import Element, TextElement, Structural, Inline, Part, \
     Text
import types

# This is the parent class of all the other pynode classes:
class PythonStructural(Structural): pass

# =====================
#  Structural Elements
# =====================

class module_section(PythonStructural, Element): pass    
class class_section(PythonStructural, Element): pass
class class_base(PythonStructural, Element): pass
class method_section(PythonStructural, Element): pass
class attribute(PythonStructural, Element): pass
class function_section(PythonStructural, Element): pass
class class_attribute_section(PythonStructural, Element): pass
class class_attribute(PythonStructural, Element): pass
class expression_value(PythonStructural, Element): pass
class attribute(PythonStructural, Element): pass

# Structural Support Elements
# ---------------------------

class parameter_list(PythonStructural, Element): pass
class parameter_tuple(PythonStructural, Element): pass
class parameter_default(PythonStructural, TextElement): pass
class import_group(PythonStructural, TextElement): pass
class import_from(PythonStructural, TextElement): pass
class import_name(PythonStructural, TextElement): pass
class import_alias(PythonStructural, TextElement): pass
class docstring(PythonStructural, Element): pass

# =================
#  Inline Elements
# =================

# These elements cannot become references until the second
# pass.  Initially, we'll use "reference" or "name".

class object_name(PythonStructural, TextElement): pass
class parameter_list(PythonStructural, TextElement): pass
class parameter(PythonStructural, TextElement): pass
class parameter_default(PythonStructural, TextElement): pass
class class_attribute(PythonStructural, TextElement): pass
class attribute_tuple(PythonStructural, TextElement): pass

# =================
#  Unused Elements
# =================

# These were part of the model, and maybe should be in the future, but
# aren't now.
#class package_section(PythonStructural, Element): pass
#class module_attribute_section(PythonStructural, Element): pass
#class instance_attribute_section(PythonStructural, Element): pass
#class module_attribute(PythonStructural, TextElement): pass
#class instance_attribute(PythonStructural, TextElement): pass
#class exception_class(PythonStructural, TextElement): pass
#class warning_class(PythonStructural, TextElement): pass


# Collect all the classes we've written above
def install_node_class_names():
    node_class_names = []
    for name, var in globals().items():
        if (type(var) is types.ClassType
            and issubclass(var, PythonStructural) \
            and name.lower() == name):
            node_class_names.append(var.tagname or name)
    # Register the new node names with GenericNodeVisitor and
    # SpecificNodeVisitor:
    nodes._add_node_class_names(node_class_names)
install_node_class_names()
�������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/standalone.py������������������������������������0000644�0001750�0001750�00000004551�10322224711�024735� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3353 $
# Date: $Date: 2005-05-19 02:49:14 +0200 (Thu, 19 May 2005) $
# Copyright: This module has been placed in the public domain.

"""
Standalone file Reader for the reStructuredText markup syntax.
"""

__docformat__ = 'reStructuredText'


import sys
from docutils import frontend, readers
from docutils.transforms import frontmatter, references


class Reader(readers.Reader):

    supported = ('standalone',)
    """Contexts this reader supports."""

    document = None
    """A single document tree."""

    settings_spec = (
        'Standalone Reader',
        None,
        (('Disable the promotion of a lone top-level section title to '
          'document title (and subsequent section title to document '
          'subtitle promotion; enabled by default).',
          ['--no-doc-title'],
          {'dest': 'doctitle_xform', 'action': 'store_false', 'default': 1,
           'validator': frontend.validate_boolean}),
         ('Disable the bibliographic field list transform (enabled by '
          'default).',
          ['--no-doc-info'],
          {'dest': 'docinfo_xform', 'action': 'store_false', 'default': 1,
           'validator': frontend.validate_boolean}),
         ('Activate the promotion of lone subsection titles to '
          'section subtitles (disabled by default).',
          ['--section-subtitles'],
          {'dest': 'sectsubtitle_xform', 'action': 'store_true', 'default': 0,
           'validator': frontend.validate_boolean}),
         ('Deactivate the promotion of lone subsection titles.',
          ['--no-section-subtitles'],
          {'dest': 'sectsubtitle_xform', 'action': 'store_false',
           'validator': frontend.validate_boolean}),
         ))

    config_section = 'standalone reader'
    config_section_dependencies = ('readers',)

    default_transforms = (references.Substitutions,
                          references.PropagateTargets,
                          frontmatter.DocTitle,
                          frontmatter.SectionSubTitle,
                          frontmatter.DocInfo,
                          references.AnonymousHyperlinks,
                          references.IndirectHyperlinks,
                          references.Footnotes,
                          references.ExternalTargets,
                          references.InternalTargets,)
�������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/__init__.py��������������������������������������0000644�0001750�0001750�00000005347�10322224711�024350� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Authors: David Goodger; Ueli Schlaepfer
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 1645 $
# Date: $Date: 2003-08-27 22:50:43 +0200 (Wed, 27 Aug 2003) $
# Copyright: This module has been placed in the public domain.

"""
This package contains Docutils Reader modules.
"""

__docformat__ = 'reStructuredText'


import sys
from docutils import utils, parsers, Component
from docutils.transforms import universal


class Reader(Component):

    """
    Abstract base class for docutils Readers.

    Each reader module or package must export a subclass also called 'Reader'.

    The three steps of a Reader's responsibility are defined: `scan()`,
    `parse()`, and `transform()`. Call `read()` to process a document.
    """

    component_type = 'reader'
    config_section = 'readers'

    def __init__(self, parser=None, parser_name='restructuredtext'):
        """
        Initialize the Reader instance.

        Several instance attributes are defined with dummy initial values.
        Subclasses may use these attributes as they wish.
        """

        self.parser = parser
        """A `parsers.Parser` instance shared by all doctrees.  May be left
        unspecified if the document source determines the parser."""

        if parser is None and parser_name:
            self.set_parser(parser_name)

        self.source = None
        """`docutils.io` IO object, source of input data."""

        self.input = None
        """Raw text input; either a single string or, for more complex cases,
        a collection of strings."""

    def set_parser(self, parser_name):
        """Set `self.parser` by name."""
        parser_class = parsers.get_parser_class(parser_name)
        self.parser = parser_class()

    def read(self, source, parser, settings):
        self.source = source
        if not self.parser:
            self.parser = parser
        self.settings = settings
        self.input = self.source.read()
        self.parse()
        return self.document

    def parse(self):
        """Parse `self.input` into a document tree."""
        self.document = document = self.new_document()
        self.parser.parse(self.input, document)
        document.current_source = document.current_line = None

    def new_document(self):
        """Create and return a new empty document tree (root node)."""
        document = utils.new_document(self.source.source_path, self.settings)
        return document


_reader_aliases = {}

def get_reader_class(reader_name):
    """Return the Reader class from the `reader_name` module."""
    reader_name = reader_name.lower()
    if _reader_aliases.has_key(reader_name):
        reader_name = _reader_aliases[reader_name]
    module = __import__(reader_name, globals(), locals())
    return module.Reader
�����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/readers/pep.py�������������������������������������������0000644�0001750�0001750�00000003253�10322224711�023367� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3129 $
# Date: $Date: 2005-03-26 17:21:28 +0100 (Sat, 26 Mar 2005) $
# Copyright: This module has been placed in the public domain.

"""
Python Enhancement Proposal (PEP) Reader.
"""

__docformat__ = 'reStructuredText'


from docutils.readers import standalone
from docutils.transforms import peps, references
from docutils.parsers import rst


class Reader(standalone.Reader):

    supported = ('pep',)
    """Contexts this reader supports."""

    settings_spec = (
        'PEP Reader Option Defaults',
        'The --pep-references and --rfc-references options (for the '
        'reStructuredText parser) are on by default.',
        ())

    config_section = 'pep reader'
    config_section_dependencies = ('readers', 'standalone reader')

    default_transforms = (references.Substitutions,
                          references.PropagateTargets,
                          peps.Headers,
                          peps.Contents,
                          references.AnonymousHyperlinks,
                          references.IndirectHyperlinks,
                          peps.TargetNotes,
                          references.Footnotes,
                          references.ExternalTargets,
                          references.InternalTargets,)

    settings_default_overrides = {'pep_references': 1, 'rfc_references': 1}

    inliner_class = rst.states.Inliner

    def __init__(self, parser=None, parser_name=None):
        """`parser` should be ``None``."""
        if parser is None:
            parser = rst.Parser(rfc2822=1, inliner=self.inliner_class())
        standalone.Reader.__init__(self, parser, '')
�����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/__init__.py����������������������������������������������0000644�0001750�0001750�00000013750�10322224711�022720� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������# Author: David Goodger
# Contact: goodger@python.org
# Revision: $Revision: 3374 $
# Date: $Date: 2005-05-26 23:21:48 +0200 (Thu, 26 May 2005) $
# Copyright: This module has been placed in the public domain.

"""
This is the Docutils (Python Documentation Utilities) package.

Package Structure
=================

Modules:

- __init__.py: Contains component base classes, exception classes, and
  Docutils `__version__`.

- core.py: Contains the ``Publisher`` class and ``publish_*()`` convenience
  functions.

- frontend.py: Runtime settings (command-line interface, configuration files)
  processing, for Docutils front-ends.

- io.py: Provides a uniform API for low-level input and output.

- nodes.py: Docutils document tree (doctree) node class library.

- statemachine.py: A finite state machine specialized for
  regular-expression-based text filters.

- urischemes.py: Contains a complete mapping of known URI addressing
  scheme names to descriptions.

- utils.py: Contains the ``Reporter`` system warning class and miscellaneous
  utilities.

Subpackages:

- languages: Language-specific mappings of terms.

- parsers: Syntax-specific input parser modules or packages.

- readers: Context-specific input handlers which understand the data
  source and manage a parser.

- transforms: Modules used by readers and writers to modify DPS
  doctrees.

- writers: Format-specific output translators.
"""

__docformat__ = 'reStructuredText'

__version__ = '0.3.9'
"""``major.minor.micro`` version number.  The micro number is bumped for API
changes, for new functionality, and for interim project releases.  The minor
number is bumped whenever there is a significant project release.  The major
number will be bumped when the project is feature-complete, and perhaps if
there is a major change in the design."""


class ApplicationError(StandardError): pass
class DataError(ApplicationError): pass


class SettingsSpec:

    """
    Runtime setting specification base class.

    SettingsSpec subclass objects used by `docutils.frontend.OptionParser`.
    """

    settings_spec = ()
    """Runtime settings specification.  Override in subclasses.

    Defines runtime settings and associated command-line options, as used by
    `docutils.frontend.OptionParser`.  This is a tuple of:

    - Option group title (string or `None` which implies no group, just a list
      of single options).
    
    - Description (string or `None`).
    
    - A sequence of option tuples.  Each consists of:

      - Help text (string)
      
      - List of option strings (e.g. ``['-Q', '--quux']``).
      
      - Dictionary of keyword arguments.  It contains arguments to the
        OptionParser/OptionGroup ``add_option`` method, possibly with the
        addition of a 'validator' keyword (see the
        `docutils.frontend.OptionParser.validators` instance attribute).  Runtime
        settings names are derived implicitly from long option names
        ('--a-setting' becomes ``settings.a_setting``) or explicitly from the
        'dest' keyword argument.  See optparse docs for more details.

    - More triples of group title, description, options, as many times as
      needed.  Thus, `settings_spec` tuples can be simply concatenated.
    """

    settings_defaults = None
    """A dictionary of defaults for settings not in `settings_spec` (internal
    settings, intended to be inaccessible by command-line and config file).
    Override in subclasses."""

    settings_default_overrides = None
    """A dictionary of auxiliary defaults, to override defaults for settings
    defined in other components.  Override in subclasses."""

    relative_path_settings = ()
    """Settings containing filesystem paths.  Override in subclasses.
    Settings listed here are to be interpreted relative to the current working
    directory."""

    config_section = None
    """The name of the config file section specific to this component
    (lowercase, no brackets).  Override in subclasses."""

    config_section_dependencies = None
    """A list of names of config file sections that are to be applied before
    `config_section`, in order (from general to specific).  In other words,
    the settings in `config_section` are to be overlaid on top of the settings
    from these sections.  The "general" section is assumed implicitly.
    Override in subclasses."""


class TransformSpec:

    """
    Runtime transform specification base class.

    TransformSpec subclass objects used by `docutils.transforms.Transformer`.
    """

    default_transforms = ()
    """Transforms required by this class.  Override in subclasses."""
    
    unknown_reference_resolvers = ()
    """List of functions to try to resolve unknown references.  Unknown
    references have a 'refname' attribute which doesn't correspond to any
    target in the document.  Called when FinalCheckVisitor is unable to find a
    correct target.  The list should contain functions which will try to
    resolve unknown references, with the following signature::

        def reference_resolver(node):
            '''Returns boolean: true if resolved, false if not.'''

    If the function is able to resolve the reference, it should also remove
    the 'refname' attribute and mark the node as resolved::

        del node['refname']
        node.resolved = 1

    Each function must have a "priority" attribute which will affect the order
    the unknown_reference_resolvers are run::

        reference_resolver.priority = 100

    Override in subclasses."""


class Component(SettingsSpec, TransformSpec):

    """Base class for Docutils components."""

    component_type = None
    """Name of the component type ('reader', 'parser', 'writer').  Override in
    subclasses."""

    supported = ()
    """Names for this component.  Override in subclasses."""
    
    def supports(self, format):
        """
        Is `format` supported by this component?

        To be used by transforms to ask the dependent component if it supports
        a certain input context or output format.
        """
        return format in self.supported
������������������������Zope-2.9.4-retire_zpkg/lib/python/docutils/FAQ.txt��������������������������������������������������0000644�0001750�0001750�00000110175�10172235404�021762� 0����������������������������������������������������������������������������������������������������ustar  �tseaver�������������������������tseaver����������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������������===========================================
 Docutils FAQ (Frequently Asked Questions)
===========================================

:Date: $Date: 2005/01/07 15:11:43 $
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.

.. Please note that until there's a Q&A-specific construct available,
   this FAQ will use section titles for questions.  Therefore
   questions must fit on one line.  The title may be a summary of the
   question, with the full question in the section body.


.. contents::
.. sectnum::


This is a work in progress.  Please feel free to ask questions and/or
provide answers; `send email`__ to the `Docutils-Users mailing list`__
[1]_.  Project members should feel free to edit the source text file
directly.

.. [1] Due to overwhelming amounts of spam, the
   docutils-users@lists.sourceforge.net mailing list has been set up
   for subscriber posting only.  Non-subscribers who post to
   docutils-users will receive a message with "Subject: Your message
   to Docutils-users awaits moderator approval".  Legitimate messages
   are accepted and posted as soon as possible (a list administrator
   must verify the message manually).  If you'd like to subscribe to
   docutils-users, please visit
   <http://lists.sourceforge.net/lists/listinfo/docutils-users>.

.. _let us know:
__ mailto:docutils-users@lists.sourceforge.net
__ http://lists.sourceforge.net/lists/listinfo/docutils-users


Docutils
========

What is Docutils?
-----------------

Docutils_ is a system for processing plaintext documentation into
useful formats, such as HTML, XML, and LaTeX.  It supports multiple
types of input, such as standalone files (implemented), inline
documentation from Python modules and packages (under development),
`PEPs (Python Enhancement Proposals)`_ (implemented), and others as
discovered.

For an overview of the Docutils project implementation, see `PEP
258`_, "Docutils Design Specification".

Docutils is implemented in Python_.

.. _Docutils: http://docutils.sourceforge.net/
.. _PEPs (Python Enhancement Proposals):
   http://www.python.org/peps/pep-0012.html
.. _PEP 258: http://www.python.org/peps/pep-0258.html
.. _Python: http://www.python.org/


Why is it called "Docutils"?
----------------------------

Docutils is short for "Python Documentation Utilities".  The name
"Docutils" was inspired by "Distutils", the Python Distribution
Utilities architected by Greg Ward, a component of Python's standard
library.

The earliest known use of the term "docutils" in a Python context was
a `fleeting reference`__ in a message by Fred Drake on 1999-12-02 in
the Python Doc-SIG mailing list.  It was suggested `as a project
name`__ on 2000-11-27 on Doc-SIG, again by Fred Drake, in response to
a question from Tony "Tibs" Ibbs: "What do we want to *call* this
thing?".  This was shortly after David Goodger first `announced
reStructuredText`__ on Doc-SIG.

Tibs used the name "Docutils" for `his effort`__ "to document what the
Python docutils package should support, with a particular emphasis on
documentation strings".  Tibs joined the current project (and its
predecessors) and graciously donated the name.

For more history of reStructuredText and the Docutils project, see `An
Introduction to reStructuredText`_.

Please note that the name is "Docutils", not "DocUtils" or "Doc-Utils"
or any other variation.

.. _An Introduction to reStructuredText:
   http://docutils.sourceforge.net/docs/ref/rst/introduction.html
__ http://mail.python.org/pipermail/doc-sig/1999-December/000878.html
__ http://mail.python.org/pipermail/doc-sig/2000-November/001252.html
__ http://mail.python.org/pipermail/doc-sig/2000-November/001239.html
__ http://homepage.ntlworld.com/tibsnjoan/docutils/STpy.html


Is there a GUI authoring environment for Docutils?
--------------------------------------------------

DocFactory_ is under development.  It uses wxPython and looks very
promising.

.. _DocFactory:
   http://docutils.sf.net/sandbox/gschwant/docfactory/doc/


What is the status of the Docutils project?
-------------------------------------------

Although useful and relatively stable, Docutils is experimental code,
with APIs and architecture subject to change.

Our highest priority is to fix bugs as they are reported.  So the
latest code from CVS (or `development snapshots`_) is almost always
the most stable (bug-free) as well as the most featureful.


What is the Docutils project release policy?
--------------------------------------------

It ought to be "release early & often", but official releases are a
significant effort and aren't done that often.  We have
automatically-generated `development snapshots`_ which always contain
the latest code from CVS.  As the project matures, we may formalize on
a stable/development-branch scheme, but we're not using anything like
that yet.

.. _development snapshots:
   http://docutils.sourceforge.net/#development-snapshots


reStructuredText
================

What is reStructuredText?
-------------------------

reStructuredText_ is an easy-to-read, what-you-see-is-what-you-get
plaintext markup syntax and parser system.  The reStructuredText
parser is a component of Docutils_.  reStructuredText is a revision
and reinterpretation of the StructuredText_ and Setext_ lightweight
markup systems.

If you are reading this on the web, you can see for yourself.  `The
source for this FAQ <FAQ.txt>`_ is written in reStructuredText; open
it in another window and compare them side by side.

`A ReStructuredText Primer`_ and the `Quick reStructuredText`_ user
reference are a good place to start.  The `reStructuredText Markup
Specification`_ is a detailed technical specification.

.. _A ReStructuredText Primer:
   http://docutils.sourceforge.net/docs/user/rst/quickstart.html
.. _Quick reStructuredText:
   http://docutils.sourceforge.net/docs/user/rst/quickref.html
.. _reStructuredText Markup Specification:
   http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _StructuredText:
   http://dev.zope.org/Members/jim/StructuredTextWiki/FrontPage/
.. _Setext: http://docutils.sourceforge.net/mirror/setext.html


Why is it called "reStructuredText"?
------------------------------------

The name came from a combination of "StructuredText", one of
reStructuredText's predecessors, with "re": "revised", "reworked", and
"reinterpreted", and as in the ``re.py`` regular expression module.
For a detailed history of reStructuredText and the Docutils project,
see `An Introduction to reStructuredText`_.


What's the standard abbreviation for "reStructuredText"?
--------------------------------------------------------

"RST" and "ReST" (or "reST") are both acceptable.  Care should be
taken with capitalization, to avoid confusion with "REST__", an
acronym for "Representational State Transfer".

The abbreviations "reSTX" and "rSTX"/"rstx" should **not** be used;
they overemphasize reStructuredText's precedessor, Zope's
StructuredText.

__ http://www.xml.com/pub/a/2002/02/06/rest.html


What's the standard filename extension for a reStructuredText file?
-------------------------------------------------------------------

It's ".txt".  Some people would like to use ".rest" or ".rst" or
".restx", but why bother?  ReStructuredText source files are meant to
be readable as plaintext, and most operating systems already associate
".txt" with text files.  Using a specialized filename extension would
require that users alter their OS settings, which is something that
many users will not be willing or able to do.


Are there any reStructuredText editor extensions?
-------------------------------------------------

See `Editor Support for reStructuredText`__.

__ http://docutils.sf.net/tools/editors/README.html


How can I indicate the document title?  Subtitle?
-------------------------------------------------

A uniquely-adorned section title at the beginning of a document is
treated specially, as the document title.  Similarly, a
uniquely-adorned section title immediately after the document title
becomes the document subtitle.  For example::

    This is the Document Title
    ==========================

    This is the Document Subtitle
    -----------------------------

    Here's an ordinary paragraph.

Counterexample::

    Here's an ordinary paragraph.

    This is *not* a Document Title
    ==============================

    The "ordinary paragraph" above the section title
    prevents it from becoming the document title.

Another counterexample::

    This is not the Document Title,  because...
    ===========================================

    Here's an ordinary paragraph.

    ... the title adornment is not unique
    =====================================

    Another ordinary paragraph.


How can I represent esoteric characters (e.g. character entities) in a document?
--------------------------------------------------------------------------------

For example, say you want an em-dash (XML character entity —,
Unicode character ``\u2014``) in your document: use a real em-dash.
Insert concrete characters (e.g. type a *real* em-dash) into your
input file, using whatever encoding suits your application, and tell
Docutils the input encoding.  Docutils uses Unicode internally, so the
em-dash character is a real em-dash internally.

Emacs users should refer to the `Emacs Support for reStructuredText`__
document.  Tips for other editors are welcome.

__ http://docutils.sourceforge.net/tools/editors/emacs/README.html

ReStructuredText has no character entity subsystem; it doesn't know
anything about XML charents.  To Docutils, "—" in input text is
7 discrete characters; no interpretation happens.  When writing HTML,
the "&" is converted to "&", so in the raw output you'd see
"&mdash;".  There's no difference in interpretation for text
inside or outside inline literals or literal blocks -- there's no
character entity interpretation in either case.

If you can't use a Unicode-compatible encoding and must rely on 7-bit
ASCII, there is a workaround.  Files containing character entity set
substitution definitions using the "unicode_" directive `are
available`_ (tarball_).  Please read the `description and
instructions`_ for use.  Thanks to David Priest for the original idea.
Incorporating these files into Docutils is on the `to-do list`_.
   
If you insist on using XML-style charents, you'll have to implement a
pre-processing system to convert to UTF-8 or something.  That
introduces complications though; you can no longer *write* about
charents naturally; instead of writing "—" you'd have to write
"&mdash;".

For the common case of long dashes, you might also want to insert the
following substitution definitons into your document (both of them are
using the "unicode_" directive)::

    .. |--| unicode:: U+2013   .. en dash
    .. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
       :trim:

.. |--| unicode:: U+2013   .. en dash
.. |---| unicode:: U+2014  .. em dash, trimming surrounding whitespace
   :trim:

Now you can write dashes using pure ASCII: "``foo |--| bar; foo |---|
bar``", rendered as "foo |--| bar; foo |---| bar".  (Note that Mozilla
and Firefox may render this incorrectly.)  The ``:trim:`` option for
the em dash is necessary because you cannot write "``foo|---|bar``";
thus you need to add spaces ("``foo |---| bar``") and advise the
reStructuredText parser to trim the spaces using the ``:trim:``
option.

.. _unicode:
   http://docutils.sf.net/docs/ref/rst/directives.html#unicode-character-codes
.. _are available: http://docutils.sourceforge.net/tmp/charents/
.. _tarball: http://docutils.sourceforge.net/tmp/charents.tgz
.. _description and instructions:
   http://docutils.sourceforge.net/tmp/charents/README.html
.. _to-do list: http://docutils.sourceforge.net/docs/dev/todo.html


How can I generate backticks using a Scandinavian keyboard?
-----------------------------------------------------------

The use of backticks in reStructuredText is a bit awkward with
Scandinavian keyboards, where the backtick is a "dead" key.  To get
one ` character one must press SHIFT-` + SPACE.

Unfortunately, with all the variations out there, there's no way to
please everyone.  For Scandinavian programmers and technical writers,
this is not limited to reStructuredText but affects many languages and
environments.

Possible solutions include

* If you have to input a lot of backticks, simply type one in the
  normal/awkward way, select it, copy and then paste the rest (CTRL-V
  is a lot faster than SHIFT-` + SPACE).

* Use keyboard macros.

* Remap the keyboard.  The Scandinavian keyboard layout is awkward for
  other programming/technical characters too; for example, []{}
  etc. are a bit awkward compared to US keyboards.

  According to Axel Kollmorgen,

      Under Windows, you can use the `Microsoft Keyboard Layout Creator
      <http://www.microsoft.com/globaldev/tools/msklc.mspx>`__ to easily
      map the backtick key to a real backtick (no dead key). took me
      five minutes to load my default (german) keyboard layout, untick
      "Dead Key?" from the backtick key properties ("in all shift
      states"), "build dll and setup package", install the generated
      .msi, and add my custom keyboard layout via Control Panel >
      Regional and Language Options > Languages > Details > Add
      Keyboard layout (and setting it as default "when you start your
      computer").

* Use a virtual/screen keyboard or character palette, such as:

  - `Web-based keyboards <http://keyboard.lab.co.il/>`__ (IE only
    unfortunately).
  - Windows: `Click-N-Type <http://www.lakefolks.org/cnt/>`__.
  - Mac OS X: the Character Palette can store a set of favorite
    characters for easy input.  Open System Preferences,
    International, Input Menu tab, enable "Show input menu in menu
    bar", and be sure that Character Palette is enabled in the list.

  Other options are welcome.

If anyone knows of other/better solutions, please `let us know`_.


Are there any tools for HTML/XML-to-reStructuredText?  (Round-tripping)
-----------------------------------------------------------------------

People have tossed the idea around, but little if any actual work has
ever been done.  There's no reason why reStructuredText should not be
round-trippable to/from XML; any technicalities which prevent
round-tripping would be considered bugs.  Whitespace would not be
identical, but paragraphs shouldn't suffer.  The tricky parts would be
the smaller details, like links and IDs and other bookkeeping.

For HTML, true round-tripping may not be possible.  Even adding lots
of extra "class" attributes may not be enough.  A "simple HTML" to RST
filter is possible -- for some definition of "simple HTML" -- but HTML
is used as dumb formatting so much that such a filter may not be
particularly useful.  No general-purpose filter exists.  An 80/20
approach should work though: build a tool that does 80% of the work
automatically, leaving the other 20% for manual tweaks.


Are there any Wikis that use reStructuredText syntax?
-----------------------------------------------------

There are several, with various degrees of completeness.  With no
implied endorsement or recommendation, and in no particular order:

* `Ian Bicking's experimental code
  <http://docutils.sf.net/sandbox/ianb/wiki/WikiPage.py>`__
* `MoinMoin <http://moin.sf.net>`__ has some support; `here's a sample
  <http://twistedmatrix.com/users/jh.twistd/moin/moin.cgi/RestSample>`__
* Zope-based `Zwiki <http://zwiki.org/>`__
* Zope3-based Zwiki (in the Zope 3 source tree as ``zope.products.zwiki``)
* `StikiWiki <http://mithrandr.moria.org/code/stikiwiki/>`__
* `Trac <http://projects.edgewall.com/trac/>`__ `supports using reStructuredText
  <http://projects.edgewall.com/trac/wiki/WikiRestructuredText>`__ as an
  alternative to wiki markup. This includes support for `TracLinks
  <http://projects.edgewall.com/trac/wiki/TracLinks>`__ from within RST
  text via a custom RST reference-directive or, even easier, an interpreted text
  role 'trac'
* `Vogontia <http://www.ososo.de/vogontia/>`__, a Wiki-like FAQ system

Please `let us know`_ of any other reStructuredText Wikis.

The example application for the `Web Framework Shootout
<http://colorstudy.com/docs/shootout.html>`__ article is a Wiki using
reStructuredText.


Are there any Weblog (Blog) projects that use reStructuredText syntax?
----------------------------------------------------------------------

With no implied endorsement or recommendation, and in no particular
order:

* `Python Desktop Server <http://pyds.muensterland.org/>`__
* `PyBloxsom <http://roughingit.subtlehints.net/pyblosxom/>`__
* `rst2ht <http://www.rutherfurd.net/articles/rst-ht2html.html>`__
* `htmlnav <http://docutils.sourceforge.net/sandbox/gschwant/htmlnav/>`__
* `restblog <http://docutils.sourceforge.net/sandbox/mly/restblog/>`__
* `ReSTWeb <http://wingide.com/opensource/restweb>`__
* `Lino WebMan <http://lino.sourceforge.net/webman.html>`__

Please `let us know`_ of any other reStructuredText Blogs.


Can lists be indented without generating block quotes?
------------------------------------------------------

Some people like to write lists with indentation, without intending a
block quote context, like this::

    paragraph

      * list item 1
      * list item 2

There has been a lot of discussion about this, but there are some
issues that would need to be resolved before it could be implemented.
There is a summary of the issues and pointers to the discussions in
`the to-do list`__.

__ http://docutils.sourceforge.net/docs/dev/todo.html#indented-lists


Could the requirement for blank lines around lists be relaxed?
--------------------------------------------------------------

Short answer: no.

In reStructuredText, it would be impossible to unambigously mark up
and parse lists without blank lines before and after.  Deeply nested
lists may look ugly with so many blank lines, but it's a price we pay
for unambiguous markup.  Some other plaintext markup systems do not
require blank lines in nested lists, but they have to compromise
somehow, either accepting ambiguity or requiring extra complexity.
For example, `Epytext <http://epydoc.sf.net/epytext.html#list>`__ does
not require blank lines around lists, but it does require that lists
be indented and that ambiguous cases be escaped.


How can I include mathematical equations in documents?
------------------------------------------------------

There is no elegant built-in way, yet.  There are several ideas, but
no obvious winner.  This issue requires a champion to solve the
technical and aesthetic issues and implement a generic solution.
Here's the `to-do list entry`__.

__ http://docutils.sourceforge.net/docs/dev/todo.html#math-markup

There are several quick & dirty ways to include equations in documents.
They all presently use LaTeX syntax or dialects of it.

* For LaTeX output, nothing beats raw LaTeX math.  A simple way is to
  use the `raw directive`_::

      .. raw:: latex

          \[ x^3 + 3x^2a + 3xa^2 + a^3, \]
          
  For inline math you could use substitutions of the raw directive but
  the recently added `raw role`_ is more convenient.  You must define a
  custom role based on it once in your document::

      .. role:: raw-latex(raw)
          :format: latex

  and then you can just use the new role in your text::

      the binomial expansion of :raw-latex:`$(x+a)^3$` is

  .. _raw directive: http://docutils.sourceforge.net/docs/ref/rst/
                     directives.html#raw-data-pass-through
  .. _raw role: http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw

* For HTML the "Right" w3c-standard way to include math is MathML_.
  Unfortunately its rendering is still quite broken (or absent) on many
  browsers but it's getting better.  Another bad problem is that typing
  or reading raw MathML by humans is *really* painful, so embedding it
  in a reST document with the raw directive would defy the goals of
  readability and editability of reST (see an `example of raw MathML
  <http://sf.net/mailarchive/message.php?msg_id=2177102>`__).

  A much less painful way to generate HTML+MathML is to use itex2mml_ to
  convert a dialect of LaTeX syntax to presentation MathML.  Here is an
  example of potential `itex math markup
  <http://article.gmane.org/gmane.text.docutils.user/118>`__.  The
  simplest way to use it is to add ``html`` to the format lists for the
  raw directive/role and postprocess the resulting document with
  itex2mml.  This way you can *generate LaTeX and HTML+MathML from the
  same source*, but you must limit yourself to the intersection of LaTeX
  and itex markups for this to work.  Alan G. Isaac wrote a detailed
  HOWTO_ for this approach.

  .. _MathML: http://www.w3.org/Math/
  .. _itex2mml: http://pear.math.pitt.edu/mathzilla/itex2mml.html
  .. _HOWTO: http://www.american.edu/econ/itex2mml/mathhack.rst

  * The other way to add math to HTML is to use images of the equations,
    typically generated by TeX.  This is inferior to MathML in the long
    term but is perhaps more accessible nowdays.

    Of course, doing it by hand is too much work.  Beni Cherniavsky has
    written some `preprocessing scripts`__ for converting the
    ``texmath`` role/directive into images for HTML output and raw
    directives/subsitution for LaTeX output.  This way you can *generate
    LaTeX and HTML+images from the same source*.  `Instructions here`__.

    __ http://docutils.sourceforge.net/sandbox/cben/rolehack/
    __ http://docutils.sourceforge.net/sandbox/cben/rolehack/README.html


Is nested inline markup possible?
---------------------------------

Not currently, no.  It's on the `to-do list`__ (`details here`__), and
hopefully will be part of the reStructuredText parser soon.  At that
time, markup like this will become possible::

    Here is some *emphasized text containing a `hyperlink`_ and
    ``inline literals``*.

__ http://docutils.sf.net/docs/dev/todo.html#nested-inline-markup
__ http://docutils.sf.net/docs/dev/rst/alternatives.html#nested-inline-markup

There are workarounds, but they are either convoluted or ugly or both.
They are not recommended.

* Inline markup can be combined with hyperlinks using `substitution
  definitions`__ and references__ with the `"replace" directive`__.
  For example::

      Here is an |emphasized hyperlink|_.

      .. |emphasized hyperlink| replace:: *emphasized hyperlink*
      .. _emphasized hyperlink: http://example.org

  It is not possible for just a portion of the replacement text to be
  a hyperlink; it's the entire replacement text or nothing.

  __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-definitions
  __ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#substitution-references
  __ http://docutils.sf.net/docs/ref/rst/directives.html#replace

* The `"raw" directive`__ can be used to insert raw HTML into HTML
  output::

      Here is some |stuff|.

      .. |stuff| raw:: html

         <em>emphasized text containing a
         <a href="http://example.org">hyperlink</a> and
         <tt>inline literals</tt></em>

  Raw LaTeX is supported for LaTeX output, etc.

  __ http://docutils.sf.net/docs/ref/rst/directives.html#raw


How to indicate a line break or a significant newline?
------------------------------------------------------

`Line blocks`__ are designed for address blocks, verse, and other
cases where line breaks are significant and must be preserved.  Unlike
literal blocks, the typeface is not changed, and inline markup is
recognized.  For example::

    | A one, two, a one two three four
    | 
    | Half a bee, philosophically,
    |     must, *ipso facto*, half not be.
    | But half the bee has got to be,
    |     *vis a vis* its entity.  D'you see?
    | 
    | But can a bee be said to be
    |     or not to be an entire bee,
    |         when half the bee is not a bee,
    |             due to some ancient injury?
    | 
    | Singing...

__ http://docutils.sf.net/docs/ref/rst/restructuredtext.html#line-blocks

Here's a workaround for manually inserting explicit line breaks in
HTML output::

    .. |br| raw:: html

       <br />

    I want to break this line here: |br| this is after the break.

    If the extra whitespace bothers you, |br|\ backslash-escape it.


A URL containing asterisks doesn't work.  What to do?
-----------------------------------------------------

Asterisks are valid URL characters (see :RFC:`2396`), sometimes used
in URLs.  For example::

    http://cvs.example.org/viewcvs.py/*checkout*/module/file

Unfortunately, the parser thinks the asterisks are indicating
emphasis.  The slashes serve as delineating punctuation, allowing the
asterisks to be recognized as markup.  The example above is separated
by the parser into a truncated URL, an emphasized word, and some
regular text::

    http://cvs.example.org/viewcvs.py/
    *checkout*
    /module/file

To turn off markup recognition, use a backslash to escape at least the
first asterisk, like this::

    http://cvs.example.org/viewcvs.py/\*checkout*/module/file

Escaping the second asterisk doesn't hurt, but it isn't necessary.


How can I make a literal block with *some* formatting?
------------------------------------------------------

Use the `parsed-literal`_ directive.

.. _parsed-literal: docs/ref/rst/directives.html#parsed-literal

Scenario: a document contains some source code, which calls for a
literal block to preserve linebreaks and whitespace.  But part of the
source code should be formatted, for example as emphasis or as a
hyperlink.  This calls for a *parsed* literal block::

    .. parsed-literal::

       print "Hello world!"  # *tricky* code [1]_

The emphasis (``*tricky*``) and footnote reference (``[1]_``) will be
parsed.


Can reStructuredText be used for web or generic templating?
-----------------------------------------------------------

Docutils and reStructuredText can be used with or as a component of a
templating system, but they do not themselves include templating
functionality.  Templating should simply be left to dedicated
templating systems.  Users can choose a templating system to apply to
their reStructuredText documents as best serves their interests.

There are many good templating systems for Python (ht2html_, YAPTU_,
Quixote_'s PTL, Cheetah_, etc.; see this non-exhaustive list of `some
other templating systems`_), and many more for other languages, each
with different approaches.  We invite you to try several and find one
you like.  If you adapt it to use Docutils/reStructuredText, please
consider contributing the code to Docutils or `let us know`_ and we'll
keep a list here.

.. _ht2html: http://ht2html.sourceforge.net/
.. _YAPTU:
   http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52305
.. _Quixote: http://www.mems-exchange.org/software/quixote/
.. _Cheetah: http://www.cheetahtemplate.org/
.. _some other templating systems:
   http://webware.sourceforge.net/Papers/Templates/


HTML Writer
===========

What is the status of the HTML Writer?
--------------------------------------

The HTML Writer module, ``docutils/writers/html4css1.py``, is a
proof-of-concept reference implementation.  While it is a complete
implementation, some aspects of the HTML it produces may be
incompatible with older browsers or specialized applications (such as
web templating).  Alternate implementations are welcome.


What kind of HTML does it produce?
----------------------------------

It produces XHTML compatible with the `HTML 4.01`_ and `XHTML 1.0`_
specifications (within reason; there are some incompatibilities
between the specs).  A cascading style sheet ("default.css" by
default) is required for proper viewing with a modern graphical
browser.  Correct rendering of the HTML produced depends on the CSS
support of the browser.

.. _HTML 4.01: http://www.w3.org/TR/html4/
.. _XHTML 1.0: http://www.w3.org/TR/xhtml1/


What browsers are supported?
----------------------------

No specific browser is targeted; all modern graphical browsers should
work.  Some older browsers, text-only browsers, and browsers without
full CSS support are known to produce inferior results.  Mozilla
(version 1.0 and up) and MS Internet Explorer (version 5.0 and up) are
known to give good results.  Reports of experiences with other
browsers are welcome.


Unexpected results from tools/rst2html.py: H1, H1 instead of H1, H2.  Why?
--------------------------------------------------------------------------

Here's the question in full:

    I have this text::

        Heading 1
        =========

        All my life, I wanted to be H1.

        Heading 1.1
        -----------

        But along came H1, and so shouldn't I be H2?
        No!  I'm H1!

        Heading 1.1.1
        *************

        Yeah, imagine me, I'm stuck at H3!  No?!?

    When I run it through tools/rst2html.py, I get unexpected results
    (below).  I was expecting H1, H2, then H3; instead, I get H1, H1,
    H2::

        ...
        <html lang="en">
        <head>
        ...
        <title>Heading 1
        
        
        
        

        
Heading 1
                <-- first H1
        
All my life, I wanted to be H1.

        

        
Heading 1.1
        <-- H1
        
But along came H1, and so now I must be H2.

        

        
Heading 1.1.1

        
Yeah, imagine me, I'm stuck at H3!

        ...

    What gives?

Check the "class" attribute on the H1 tags, and you will see a
difference.  The first H1 is actually ``
``; this is
the document title, and the default stylesheet renders it centered.
There can also be an ``
`` for the document
subtitle.

If there's only one highest-level section title at the beginning of a
document, it is treated specially, as the document title.  (Similarly, a
lone second-highest-level section title may become the document
subtitle.)  See `How can I indicate the document title?  Subtitle?`_ for
details.  Rather than use a plain H1 for the document title, we use ``
`` so that we can use H1 again within the document.  Why
do we do this?  HTML only has H1-H6, so by making H1 do double duty, we
effectively reserve these tags to provide 6 levels of heading beyond the
single document title.

HTML is being used for dumb formatting for nothing but final display.
A stylesheet *is required*, and one is provided:
tools/stylesheets/default.css.  Of course, you're welcome to roll your
own.  The default stylesheet provides rules to format ``
`` and ``
`` differently from
ordinary ``
`` and ``
``::

    h1.title {
      text-align: center }

    h2.subtitle {
      text-align: center }

If you don't want the top section heading to be interpreted as a
title at all, disable the `doctitle_xform`_ setting
(``--no-doc-title`` option).  This will interpret your document
differently from the standard settings, which might not be a good
idea.  If you don't like the reuse of the H1 in the HTML output, you
can tweak the `initial_header_level`_ setting
(``--initial-header-level`` option) -- but unless you match its value
to your specific document, you might end up with bad HTML (e.g. H3
without H2).

.. _doctitle_xform:
   http://docutils.sourceforge.net/docs/user/config.html#doctitle-xform
.. _initial_header_level:
   http://docutils.sourceforge.net/docs/user/config.html#initial-header-level

(Thanks to Mark McEahern for the question and much of the answer.)


Why do enumerated lists only use numbers (no letters or roman numerals)?
------------------------------------------------------------------------

The rendering of enumerators (the numbers or letters acting as list
markers) is completely governed by the stylesheet, so either the
browser can't find the stylesheet (try using the "--embed-stylesheet"
option), or the browser can't understand it (try a recent Firefox,
Mozilla, Konqueror, Opera, Safari, or even MSIE).


There appear to be garbage characters in the HTML.  What's up?
--------------------------------------------------------------

What you're seeing is most probably not garbage, but the result of a
mismatch between the actual encoding of the HTML output and the
encoding your browser is expecting.  Your browser is misinterpreting
the HTML data, which is encoded text.  A discussion of text encodings
is beyond the scope of this FAQ; see one or more of these documents
for more info:

* `UTF-8 and Unicode FAQ for Unix/Linux
  `_

* Chapters 3 and 4 of `Introduction to i18n [Internationalization]
  `_

* `Python Unicode Tutorial
  `_

* `Python Unicode Objects: Some Observations on Working With Non-ASCII
  Character Sets `_

The common case is with the default output encoding (UTF-8), when
either numbered sections are used (via the "sectnum_" directive) or
symbol-footnotes.  3 non-breaking spaces are inserted in each numbered
section title, between the generated number and the title text.  Most
footnote symbols are not available in ASCII, nor are non-breaking
spaces.  When encoded with UTF-8 and viewed with ordinary ASCII tools,
these characters will appear to be multi-character garbage.

You may have an decoding problem in your browser (or editor, etc.).
The encoding of the output is set to "utf-8", but your browswer isn't
recognizing that.  You can either try to fix your browser (enable
"UTF-8 character set", sometimes called "Unicode"), or choose a
different encoding for the HTML output.  You can also try
``--output-encoding=ascii:xmlcharrefreplace`` for HTML (not applicable
to non-XMLish outputs).

If you're generating document fragments, the "Content-Type" metadata
(between the HTML ```` and ```` tags) must agree with the
encoding of the rest of the document.  For UTF-8, it should be::

    

Also, Docutils normally generates an XML declaration as the first line
of the output.  It must also match the document encoding.  For UTF-8::

    

.. _sectnum:
   http://docutils.sourceforge.net/docs/ref/rst/directives.html#sectnum


Python Source Reader
====================

Can I use Docutils for Python auto-documentation?
-------------------------------------------------

Yes, in conjunction with other projects.

Docstring extraction functionality from within Docutils is still under
development.  There is most of a source code parsing module in
docutils/readers/python/moduleparser.py.  We do plan to finish it
eventually.  Ian Bicking wrote an initial front end for the
moduleparser.py module, in sandbox/ianb/extractor/extractor.py.  Ian
also did some work on the Python Source Reader
(docutils.readers.python) component at PyCon DC 2004.

Version 2.0 of Ed Loper's `Epydoc `_
supports reStructuredText-format docstrings for HTML output.  Docutils
0.3 or newer is required.  Development of a Docutils-specific
auto-documentation tool will continue.  Epydoc works by importing
Python modules to be documented, whereas the Docutils-specific tool,
described above, will parse modules without importing them (as with
`HappyDoc `_, which doesn't support
reStructuredText).

The advantages of parsing over importing are security and flexibility;
the disadvantage is complexity/difficulty.

* Security: untrusted code that shouldn't be executed can be parsed;
  importing a module executes its top-level code.
* Flexibility: comments and unofficial docstrings (those not supported
  by Python syntax) can only be processed by parsing.
* Complexity/difficulty: it's a lot harder to parse and analyze a
  module than it is to ``import`` and analyze one.

For more details, please see "Docstring Extraction Rules" in `PEP
258`_, item 3 ("How").


Miscellaneous
=============

Is the Docutils document model based on any existing XML models?
----------------------------------------------------------------

Not directly, no.  It borrows bits from DocBook, HTML, and others.  I
(David Goodger) have designed several document models over the years,
and have my own biases.  The Docutils document model is designed for
simplicity and extensibility, and has been influenced by the needs of
the reStructuredText markup.
Zope-2.9.4-retire_zpkg/lib/python/docutils/statemachine.py0000644000175000017500000015214010322224711023623 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 2299 $
# Date: $Date: 2004-06-17 23:46:50 +0200 (Thu, 17 Jun 2004) $
# Copyright: This module has been placed in the public domain.

"""
A finite state machine specialized for regular-expression-based text filters,
this module defines the following classes:

- `StateMachine`, a state machine
- `State`, a state superclass
- `StateMachineWS`, a whitespace-sensitive version of `StateMachine`
- `StateWS`, a state superclass for use with `StateMachineWS`
- `SearchStateMachine`, uses `re.search()` instead of `re.match()`
- `SearchStateMachineWS`, uses `re.search()` instead of `re.match()`
- `ViewList`, extends standard Python lists.
- `StringList`, string-specific ViewList.

Exception classes:

- `StateMachineError`
- `UnknownStateError`
- `DuplicateStateError`
- `UnknownTransitionError`
- `DuplicateTransitionError`
- `TransitionPatternNotFound`
- `TransitionMethodNotFound`
- `UnexpectedIndentationError`
- `TransitionCorrection`: Raised to switch to another transition.
- `StateCorrection`: Raised to switch to another state & transition.

Functions:

- `string2lines()`: split a multi-line string into a list of one-line strings


How To Use This Module
======================
(See the individual classes, methods, and attributes for details.)

1. Import it: ``import statemachine`` or ``from statemachine import ...``.
   You will also need to ``import re``.

2. Derive a subclass of `State` (or `StateWS`) for each state in your state
   machine::

       class MyState(statemachine.State):

   Within the state's class definition:

   a) Include a pattern for each transition, in `State.patterns`::

          patterns = {'atransition': r'pattern', ...}

   b) Include a list of initial transitions to be set up automatically, in
      `State.initial_transitions`::

          initial_transitions = ['atransition', ...]

   c) Define a method for each transition, with the same name as the
      transition pattern::

          def atransition(self, match, context, next_state):
              # do something
              result = [...]  # a list
              return context, next_state, result
              # context, next_state may be altered

      Transition methods may raise an `EOFError` to cut processing short.

   d) You may wish to override the `State.bof()` and/or `State.eof()` implicit
      transition methods, which handle the beginning- and end-of-file.

   e) In order to handle nested processing, you may wish to override the
      attributes `State.nested_sm` and/or `State.nested_sm_kwargs`.

      If you are using `StateWS` as a base class, in order to handle nested
      indented blocks, you may wish to:

      - override the attributes `StateWS.indent_sm`,
        `StateWS.indent_sm_kwargs`, `StateWS.known_indent_sm`, and/or
        `StateWS.known_indent_sm_kwargs`;
      - override the `StateWS.blank()` method; and/or
      - override or extend the `StateWS.indent()`, `StateWS.known_indent()`,
        and/or `StateWS.firstknown_indent()` methods.

3. Create a state machine object::

       sm = StateMachine(state_classes=[MyState, ...],
                         initial_state='MyState')

4. Obtain the input text, which needs to be converted into a tab-free list of
   one-line strings. For example, to read text from a file called
   'inputfile'::

       input_string = open('inputfile').read()
       input_lines = statemachine.string2lines(input_string)

5. Run the state machine on the input text and collect the results, a list::

       results = sm.run(input_lines)

6. Remove any lingering circular references::

       sm.unlink()
"""

__docformat__ = 'restructuredtext'

import sys
import re
from types import SliceType as _SliceType


class StateMachine:

    """
    A finite state machine for text filters using regular expressions.

    The input is provided in the form of a list of one-line strings (no
    newlines). States are subclasses of the `State` class. Transitions consist
    of regular expression patterns and transition methods, and are defined in
    each state.

    The state machine is started with the `run()` method, which returns the
    results of processing in a list.
    """

    def __init__(self, state_classes, initial_state, debug=0):
        """
        Initialize a `StateMachine` object; add state objects.

        Parameters:

        - `state_classes`: a list of `State` (sub)classes.
        - `initial_state`: a string, the class name of the initial state.
        - `debug`: a boolean; produce verbose output if true (nonzero).
        """

        self.input_lines = None
        """`StringList` of input lines (without newlines).
        Filled by `self.run()`."""

        self.input_offset = 0
        """Offset of `self.input_lines` from the beginning of the file."""

        self.line = None
        """Current input line."""

        self.line_offset = -1
        """Current input line offset from beginning of `self.input_lines`."""

        self.debug = debug
        """Debugging mode on/off."""

        self.initial_state = initial_state
        """The name of the initial state (key to `self.states`)."""

        self.current_state = initial_state
        """The name of the current state (key to `self.states`)."""

        self.states = {}
        """Mapping of {state_name: State_object}."""

        self.add_states(state_classes)

        self.observers = []
        """List of bound methods or functions to call whenever the current
        line changes.  Observers are called with one argument, ``self``.
        Cleared at the end of `run()`."""

    def unlink(self):
        """Remove circular references to objects no longer required."""
        for state in self.states.values():
            state.unlink()
        self.states = None

    def run(self, input_lines, input_offset=0, context=None,
            input_source=None):
        """
        Run the state machine on `input_lines`. Return results (a list).

        Reset `self.line_offset` and `self.current_state`. Run the
        beginning-of-file transition. Input one line at a time and check for a
        matching transition. If a match is found, call the transition method
        and possibly change the state. Store the context returned by the
        transition method to be passed on to the next transition matched.
        Accumulate the results returned by the transition methods in a list.
        Run the end-of-file transition. Finally, return the accumulated
        results.

        Parameters:

        - `input_lines`: a list of strings without newlines, or `StringList`.
        - `input_offset`: the line offset of `input_lines` from the beginning
          of the file.
        - `context`: application-specific storage.
        - `input_source`: name or path of source of `input_lines`.
        """
        self.runtime_init()
        if isinstance(input_lines, StringList):
            self.input_lines = input_lines
        else:
            self.input_lines = StringList(input_lines, source=input_source)
        self.input_offset = input_offset
        self.line_offset = -1
        self.current_state = self.initial_state
        if self.debug:
            print >>sys.stderr, (
                '\nStateMachine.run: input_lines (line_offset=%s):\n| %s'
                % (self.line_offset, '\n| '.join(self.input_lines)))
        transitions = None
        results = []
        state = self.get_state()
        try:
            if self.debug:
                print >>sys.stderr, ('\nStateMachine.run: bof transition')
            context, result = state.bof(context)
            results.extend(result)
            while 1:
                try:
                    try:
                        self.next_line()
                        if self.debug:
                            source, offset = self.input_lines.info(
                                self.line_offset)
                            print >>sys.stderr, (
                                '\nStateMachine.run: line (source=%r, '
                                'offset=%r):\n| %s'
                                % (source, offset, self.line))
                        context, next_state, result = self.check_line(
                            context, state, transitions)
                    except EOFError:
                        if self.debug:
                            print >>sys.stderr, (
                                '\nStateMachine.run: %s.eof transition'
                                % state.__class__.__name__)
                        result = state.eof(context)
                        results.extend(result)
                        break
                    else:
                        results.extend(result)
                except TransitionCorrection, exception:
                    self.previous_line() # back up for another try
                    transitions = (exception.args[0],)
                    if self.debug:
                        print >>sys.stderr, (
                              '\nStateMachine.run: TransitionCorrection to '
                              'state "%s", transition %s.'
                              % (state.__class__.__name__, transitions[0]))
                    continue
                except StateCorrection, exception:
                    self.previous_line() # back up for another try
                    next_state = exception.args[0]
                    if len(exception.args) == 1:
                        transitions = None
                    else:
                        transitions = (exception.args[1],)
                    if self.debug:
                        print >>sys.stderr, (
                              '\nStateMachine.run: StateCorrection to state '
                              '"%s", transition %s.'
                              % (next_state, transitions[0]))
                else:
                    transitions = None
                state = self.get_state(next_state)
        except:
            if self.debug:
                self.error()
            raise
        self.observers = []
        return results

    def get_state(self, next_state=None):
        """
        Return current state object; set it first if `next_state` given.

        Parameter `next_state`: a string, the name of the next state.

        Exception: `UnknownStateError` raised if `next_state` unknown.
        """
        if next_state:
            if self.debug and next_state != self.current_state:
                print >>sys.stderr, \
                      ('\nStateMachine.get_state: Changing state from '
                       '"%s" to "%s" (input line %s).'
                       % (self.current_state, next_state,
                          self.abs_line_number()))
            self.current_state = next_state
        try:
            return self.states[self.current_state]
        except KeyError:
            raise UnknownStateError(self.current_state)

    def next_line(self, n=1):
        """Load `self.line` with the `n`'th next line and return it."""
        try:
            try:
                self.line_offset += n
                self.line = self.input_lines[self.line_offset]
            except IndexError:
                self.line = None
                raise EOFError
            return self.line
        finally:
            self.notify_observers()

    def is_next_line_blank(self):
        """Return 1 if the next line is blank or non-existant."""
        try:
            return not self.input_lines[self.line_offset + 1].strip()
        except IndexError:
            return 1

    def at_eof(self):
        """Return 1 if the input is at or past end-of-file."""
        return self.line_offset >= len(self.input_lines) - 1

    def at_bof(self):
        """Return 1 if the input is at or before beginning-of-file."""
        return self.line_offset <= 0

    def previous_line(self, n=1):
        """Load `self.line` with the `n`'th previous line and return it."""
        self.line_offset -= n
        if self.line_offset < 0:
            self.line = None
        else:
            self.line = self.input_lines[self.line_offset]
        self.notify_observers()
        return self.line

    def goto_line(self, line_offset):
        """Jump to absolute line offset `line_offset`, load and return it."""
        try:
            try:
                self.line_offset = line_offset - self.input_offset
                self.line = self.input_lines[self.line_offset]
            except IndexError:
                self.line = None
                raise EOFError
            return self.line
        finally:
            self.notify_observers()

    def get_source(self, line_offset):
        """Return source of line at absolute line offset `line_offset`."""
        return self.input_lines.source(line_offset - self.input_offset)

    def abs_line_offset(self):
        """Return line offset of current line, from beginning of file."""
        return self.line_offset + self.input_offset

    def abs_line_number(self):
        """Return line number of current line (counting from 1)."""
        return self.line_offset + self.input_offset + 1

    def insert_input(self, input_lines, source):
        self.input_lines.insert(self.line_offset + 1, '',
                                source='internal padding')
        self.input_lines.insert(self.line_offset + 1, '',
                                source='internal padding')
        self.input_lines.insert(self.line_offset + 2,
                                StringList(input_lines, source))

    def get_text_block(self, flush_left=0):
        """
        Return a contiguous block of text.

        If `flush_left` is true, raise `UnexpectedIndentationError` if an
        indented line is encountered before the text block ends (with a blank
        line).
        """
        try:
            block = self.input_lines.get_text_block(self.line_offset,
                                                    flush_left)
            self.next_line(len(block) - 1)
            return block
        except UnexpectedIndentationError, error:
            block, source, lineno = error
            self.next_line(len(block) - 1) # advance to last line of block
            raise

    def check_line(self, context, state, transitions=None):
        """
        Examine one line of input for a transition match & execute its method.

        Parameters:

        - `context`: application-dependent storage.
        - `state`: a `State` object, the current state.
        - `transitions`: an optional ordered list of transition names to try,
          instead of ``state.transition_order``.

        Return the values returned by the transition method:

        - context: possibly modified from the parameter `context`;
        - next state name (`State` subclass name);
        - the result output of the transition, a list.

        When there is no match, ``state.no_match()`` is called and its return
        value is returned.
        """
        if transitions is None:
            transitions =  state.transition_order
        state_correction = None
        if self.debug:
            print >>sys.stderr, (
                  '\nStateMachine.check_line: state="%s", transitions=%r.'
                  % (state.__class__.__name__, transitions))
        for name in transitions:
            pattern, method, next_state = state.transitions[name]
            match = self.match(pattern)
            if match:
                if self.debug:
                    print >>sys.stderr, (
                          '\nStateMachine.check_line: Matched transition '
                          '"%s" in state "%s".'
                          % (name, state.__class__.__name__))
                return method(match, context, next_state)
        else:
            if self.debug:
                print >>sys.stderr, (
                      '\nStateMachine.check_line: No match in state "%s".'
                      % state.__class__.__name__)
            return state.no_match(context, transitions)

    def match(self, pattern):
        """
        Return the result of a regular expression match.

        Parameter `pattern`: an `re` compiled regular expression.
        """
        return pattern.match(self.line)

    def add_state(self, state_class):
        """
        Initialize & add a `state_class` (`State` subclass) object.

        Exception: `DuplicateStateError` raised if `state_class` was already
        added.
        """
        statename = state_class.__name__
        if self.states.has_key(statename):
            raise DuplicateStateError(statename)
        self.states[statename] = state_class(self, self.debug)

    def add_states(self, state_classes):
        """
        Add `state_classes` (a list of `State` subclasses).
        """
        for state_class in state_classes:
            self.add_state(state_class)

    def runtime_init(self):
        """
        Initialize `self.states`.
        """
        for state in self.states.values():
            state.runtime_init()

    def error(self):
        """Report error details."""
        type, value, module, line, function = _exception_data()
        print >>sys.stderr, '%s: %s' % (type, value)
        print >>sys.stderr, 'input line %s' % (self.abs_line_number())
        print >>sys.stderr, ('module %s, line %s, function %s'
                             % (module, line, function))

    def attach_observer(self, observer):
        """
        The `observer` parameter is a function or bound method which takes two
        arguments, the source and offset of the current line.
        """
        self.observers.append(observer)

    def detach_observer(self, observer):
        self.observers.remove(observer)

    def notify_observers(self):
        for observer in self.observers:
            try:
                info = self.input_lines.info(self.line_offset)
            except IndexError:
                info = (None, None)
            observer(*info)


class State:

    """
    State superclass. Contains a list of transitions, and transition methods.

    Transition methods all have the same signature. They take 3 parameters:

    - An `re` match object. ``match.string`` contains the matched input line,
      ``match.start()`` gives the start index of the match, and
      ``match.end()`` gives the end index.
    - A context object, whose meaning is application-defined (initial value
      ``None``). It can be used to store any information required by the state
      machine, and the retured context is passed on to the next transition
      method unchanged.
    - The name of the next state, a string, taken from the transitions list;
      normally it is returned unchanged, but it may be altered by the
      transition method if necessary.

    Transition methods all return a 3-tuple:

    - A context object, as (potentially) modified by the transition method.
    - The next state name (a return value of ``None`` means no state change).
    - The processing result, a list, which is accumulated by the state
      machine.

    Transition methods may raise an `EOFError` to cut processing short.

    There are two implicit transitions, and corresponding transition methods
    are defined: `bof()` handles the beginning-of-file, and `eof()` handles
    the end-of-file. These methods have non-standard signatures and return
    values. `bof()` returns the initial context and results, and may be used
    to return a header string, or do any other processing needed. `eof()`
    should handle any remaining context and wrap things up; it returns the
    final processing result.

    Typical applications need only subclass `State` (or a subclass), set the
    `patterns` and `initial_transitions` class attributes, and provide
    corresponding transition methods. The default object initialization will
    take care of constructing the list of transitions.
    """

    patterns = None
    """
    {Name: pattern} mapping, used by `make_transition()`. Each pattern may
    be a string or a compiled `re` pattern. Override in subclasses.
    """

    initial_transitions = None
    """
    A list of transitions to initialize when a `State` is instantiated.
    Each entry is either a transition name string, or a (transition name, next
    state name) pair. See `make_transitions()`. Override in subclasses.
    """

    nested_sm = None
    """
    The `StateMachine` class for handling nested processing.

    If left as ``None``, `nested_sm` defaults to the class of the state's
    controlling state machine. Override it in subclasses to avoid the default.
    """

    nested_sm_kwargs = None
    """
    Keyword arguments dictionary, passed to the `nested_sm` constructor.

    Two keys must have entries in the dictionary:

    - Key 'state_classes' must be set to a list of `State` classes.
    - Key 'initial_state' must be set to the name of the initial state class.

    If `nested_sm_kwargs` is left as ``None``, 'state_classes' defaults to the
    class of the current state, and 'initial_state' defaults to the name of
    the class of the current state. Override in subclasses to avoid the
    defaults.
    """

    def __init__(self, state_machine, debug=0):
        """
        Initialize a `State` object; make & add initial transitions.

        Parameters:

        - `statemachine`: the controlling `StateMachine` object.
        - `debug`: a boolean; produce verbose output if true (nonzero).
        """

        self.transition_order = []
        """A list of transition names in search order."""

        self.transitions = {}
        """
        A mapping of transition names to 3-tuples containing
        (compiled_pattern, transition_method, next_state_name). Initialized as
        an instance attribute dynamically (instead of as a class attribute)
        because it may make forward references to patterns and methods in this
        or other classes.
        """

        self.add_initial_transitions()

        self.state_machine = state_machine
        """A reference to the controlling `StateMachine` object."""

        self.debug = debug
        """Debugging mode on/off."""

        if self.nested_sm is None:
            self.nested_sm = self.state_machine.__class__
        if self.nested_sm_kwargs is None:
            self.nested_sm_kwargs = {'state_classes': [self.__class__],
                                     'initial_state': self.__class__.__name__}

    def runtime_init(self):
        """
        Initialize this `State` before running the state machine; called from
        `self.state_machine.run()`.
        """
        pass

    def unlink(self):
        """Remove circular references to objects no longer required."""
        self.state_machine = None

    def add_initial_transitions(self):
        """Make and add transitions listed in `self.initial_transitions`."""
        if self.initial_transitions:
            names, transitions = self.make_transitions(
                  self.initial_transitions)
            self.add_transitions(names, transitions)

    def add_transitions(self, names, transitions):
        """
        Add a list of transitions to the start of the transition list.

        Parameters:

        - `names`: a list of transition names.
        - `transitions`: a mapping of names to transition tuples.

        Exceptions: `DuplicateTransitionError`, `UnknownTransitionError`.
        """
        for name in names:
            if self.transitions.has_key(name):
                raise DuplicateTransitionError(name)
            if not transitions.has_key(name):
                raise UnknownTransitionError(name)
        self.transition_order[:0] = names
        self.transitions.update(transitions)

    def add_transition(self, name, transition):
        """
        Add a transition to the start of the transition list.

        Parameter `transition`: a ready-made transition 3-tuple.

        Exception: `DuplicateTransitionError`.
        """
        if self.transitions.has_key(name):
            raise DuplicateTransitionError(name)
        self.transition_order[:0] = [name]
        self.transitions[name] = transition

    def remove_transition(self, name):
        """
        Remove a transition by `name`.

        Exception: `UnknownTransitionError`.
        """
        try:
            del self.transitions[name]
            self.transition_order.remove(name)
        except:
            raise UnknownTransitionError(name)

    def make_transition(self, name, next_state=None):
        """
        Make & return a transition tuple based on `name`.

        This is a convenience function to simplify transition creation.

        Parameters:

        - `name`: a string, the name of the transition pattern & method. This
          `State` object must have a method called '`name`', and a dictionary
          `self.patterns` containing a key '`name`'.
        - `next_state`: a string, the name of the next `State` object for this
          transition. A value of ``None`` (or absent) implies no state change
          (i.e., continue with the same state).

        Exceptions: `TransitionPatternNotFound`, `TransitionMethodNotFound`.
        """
        if next_state is None:
            next_state = self.__class__.__name__
        try:
            pattern = self.patterns[name]
            if not hasattr(pattern, 'match'):
                pattern = re.compile(pattern)
        except KeyError:
            raise TransitionPatternNotFound(
                  '%s.patterns[%r]' % (self.__class__.__name__, name))
        try:
            method = getattr(self, name)
        except AttributeError:
            raise TransitionMethodNotFound(
                  '%s.%s' % (self.__class__.__name__, name))
        return (pattern, method, next_state)

    def make_transitions(self, name_list):
        """
        Return a list of transition names and a transition mapping.

        Parameter `name_list`: a list, where each entry is either a transition
        name string, or a 1- or 2-tuple (transition name, optional next state
        name).
        """
        stringtype = type('')
        names = []
        transitions = {}
        for namestate in name_list:
            if type(namestate) is stringtype:
                transitions[namestate] = self.make_transition(namestate)
                names.append(namestate)
            else:
                transitions[namestate[0]] = self.make_transition(*namestate)
                names.append(namestate[0])
        return names, transitions

    def no_match(self, context, transitions):
        """
        Called when there is no match from `StateMachine.check_line()`.

        Return the same values returned by transition methods:

        - context: unchanged;
        - next state name: ``None``;
        - empty result list.

        Override in subclasses to catch this event.
        """
        return context, None, []

    def bof(self, context):
        """
        Handle beginning-of-file. Return unchanged `context`, empty result.

        Override in subclasses.

        Parameter `context`: application-defined storage.
        """
        return context, []

    def eof(self, context):
        """
        Handle end-of-file. Return empty result.

        Override in subclasses.

        Parameter `context`: application-defined storage.
        """
        return []

    def nop(self, match, context, next_state):
        """
        A "do nothing" transition method.

        Return unchanged `context` & `next_state`, empty result. Useful for
        simple state changes (actionless transitions).
        """
        return context, next_state, []


class StateMachineWS(StateMachine):

    """
    `StateMachine` subclass specialized for whitespace recognition.

    There are three methods provided for extracting indented text blocks:
    
    - `get_indented()`: use when the indent is unknown.
    - `get_known_indented()`: use when the indent is known for all lines.
    - `get_first_known_indented()`: use when only the first line's indent is
      known.
    """

    def get_indented(self, until_blank=0, strip_indent=1):
        """
        Return a block of indented lines of text, and info.

        Extract an indented block where the indent is unknown for all lines.

        :Parameters:
            - `until_blank`: Stop collecting at the first blank line if true
              (1).
            - `strip_indent`: Strip common leading indent if true (1,
              default).

        :Return:
            - the indented block (a list of lines of text),
            - its indent,
            - its first line offset from BOF, and
            - whether or not it finished with a blank line.
        """
        offset = self.abs_line_offset()
        indented, indent, blank_finish = self.input_lines.get_indented(
              self.line_offset, until_blank, strip_indent)
        if indented:
            self.next_line(len(indented) - 1) # advance to last indented line
        while indented and not indented[0].strip():
            indented.trim_start()
            offset += 1
        return indented, indent, offset, blank_finish

    def get_known_indented(self, indent, until_blank=0, strip_indent=1):
        """
        Return an indented block and info.

        Extract an indented block where the indent is known for all lines.
        Starting with the current line, extract the entire text block with at
        least `indent` indentation (which must be whitespace, except for the
        first line).

        :Parameters:
            - `indent`: The number of indent columns/characters.
            - `until_blank`: Stop collecting at the first blank line if true
              (1).
            - `strip_indent`: Strip `indent` characters of indentation if true
              (1, default).

        :Return:
            - the indented block,
            - its first line offset from BOF, and
            - whether or not it finished with a blank line.
        """
        offset = self.abs_line_offset()
        indented, indent, blank_finish = self.input_lines.get_indented(
              self.line_offset, until_blank, strip_indent,
              block_indent=indent)
        self.next_line(len(indented) - 1) # advance to last indented line
        while indented and not indented[0].strip():
            indented.trim_start()
            offset += 1
        return indented, offset, blank_finish

    def get_first_known_indented(self, indent, until_blank=0, strip_indent=1,
                                 strip_top=1):
        """
        Return an indented block and info.

        Extract an indented block where the indent is known for the first line
        and unknown for all other lines.

        :Parameters:
            - `indent`: The first line's indent (# of columns/characters).
            - `until_blank`: Stop collecting at the first blank line if true
              (1).
            - `strip_indent`: Strip `indent` characters of indentation if true
              (1, default).
            - `strip_top`: Strip blank lines from the beginning of the block.

        :Return:
            - the indented block,
            - its indent,
            - its first line offset from BOF, and
            - whether or not it finished with a blank line.
        """
        offset = self.abs_line_offset()
        indented, indent, blank_finish = self.input_lines.get_indented(
              self.line_offset, until_blank, strip_indent,
              first_indent=indent)
        self.next_line(len(indented) - 1) # advance to last indented line
        if strip_top:
            while indented and not indented[0].strip():
                indented.trim_start()
                offset += 1
        return indented, indent, offset, blank_finish


class StateWS(State):

    """
    State superclass specialized for whitespace (blank lines & indents).

    Use this class with `StateMachineWS`.  The transitions 'blank' (for blank
    lines) and 'indent' (for indented text blocks) are added automatically,
    before any other transitions.  The transition method `blank()` handles
    blank lines and `indent()` handles nested indented blocks.  Indented
    blocks trigger a new state machine to be created by `indent()` and run.
    The class of the state machine to be created is in `indent_sm`, and the
    constructor keyword arguments are in the dictionary `indent_sm_kwargs`.

    The methods `known_indent()` and `firstknown_indent()` are provided for
    indented blocks where the indent (all lines' and first line's only,
    respectively) is known to the transition method, along with the attributes
    `known_indent_sm` and `known_indent_sm_kwargs`.  Neither transition method
    is triggered automatically.
    """

    indent_sm = None
    """
    The `StateMachine` class handling indented text blocks.

    If left as ``None``, `indent_sm` defaults to the value of
    `State.nested_sm`.  Override it in subclasses to avoid the default.
    """

    indent_sm_kwargs = None
    """
    Keyword arguments dictionary, passed to the `indent_sm` constructor.

    If left as ``None``, `indent_sm_kwargs` defaults to the value of
    `State.nested_sm_kwargs`. Override it in subclasses to avoid the default.
    """

    known_indent_sm = None
    """
    The `StateMachine` class handling known-indented text blocks.

    If left as ``None``, `known_indent_sm` defaults to the value of
    `indent_sm`.  Override it in subclasses to avoid the default.
    """

    known_indent_sm_kwargs = None
    """
    Keyword arguments dictionary, passed to the `known_indent_sm` constructor.

    If left as ``None``, `known_indent_sm_kwargs` defaults to the value of
    `indent_sm_kwargs`. Override it in subclasses to avoid the default.
    """

    ws_patterns = {'blank': ' *$',
                   'indent': ' +'}
    """Patterns for default whitespace transitions.  May be overridden in
    subclasses."""

    ws_initial_transitions = ('blank', 'indent')
    """Default initial whitespace transitions, added before those listed in
    `State.initial_transitions`.  May be overridden in subclasses."""

    def __init__(self, state_machine, debug=0):
        """
        Initialize a `StateSM` object; extends `State.__init__()`.

        Check for indent state machine attributes, set defaults if not set.
        """
        State.__init__(self, state_machine, debug)
        if self.indent_sm is None:
            self.indent_sm = self.nested_sm
        if self.indent_sm_kwargs is None:
            self.indent_sm_kwargs = self.nested_sm_kwargs
        if self.known_indent_sm is None:
            self.known_indent_sm = self.indent_sm
        if self.known_indent_sm_kwargs is None:
            self.known_indent_sm_kwargs = self.indent_sm_kwargs

    def add_initial_transitions(self):
        """
        Add whitespace-specific transitions before those defined in subclass.

        Extends `State.add_initial_transitions()`.
        """
        State.add_initial_transitions(self)
        if self.patterns is None:
            self.patterns = {}
        self.patterns.update(self.ws_patterns)
        names, transitions = self.make_transitions(
            self.ws_initial_transitions)
        self.add_transitions(names, transitions)

    def blank(self, match, context, next_state):
        """Handle blank lines. Does nothing. Override in subclasses."""
        return self.nop(match, context, next_state)

    def indent(self, match, context, next_state):
        """
        Handle an indented text block. Extend or override in subclasses.

        Recursively run the registered state machine for indented blocks
        (`self.indent_sm`).
        """
        indented, indent, line_offset, blank_finish = \
              self.state_machine.get_indented()
        sm = self.indent_sm(debug=self.debug, **self.indent_sm_kwargs)
        results = sm.run(indented, input_offset=line_offset)
        return context, next_state, results

    def known_indent(self, match, context, next_state):
        """
        Handle a known-indent text block. Extend or override in subclasses.

        Recursively run the registered state machine for known-indent indented
        blocks (`self.known_indent_sm`). The indent is the length of the
        match, ``match.end()``.
        """
        indented, line_offset, blank_finish = \
              self.state_machine.get_known_indented(match.end())
        sm = self.known_indent_sm(debug=self.debug,
                                 **self.known_indent_sm_kwargs)
        results = sm.run(indented, input_offset=line_offset)
        return context, next_state, results

    def first_known_indent(self, match, context, next_state):
        """
        Handle an indented text block (first line's indent known).

        Extend or override in subclasses.

        Recursively run the registered state machine for known-indent indented
        blocks (`self.known_indent_sm`). The indent is the length of the
        match, ``match.end()``.
        """
        indented, line_offset, blank_finish = \
              self.state_machine.get_first_known_indented(match.end())
        sm = self.known_indent_sm(debug=self.debug,
                                 **self.known_indent_sm_kwargs)
        results = sm.run(indented, input_offset=line_offset)
        return context, next_state, results


class _SearchOverride:

    """
    Mix-in class to override `StateMachine` regular expression behavior.

    Changes regular expression matching, from the default `re.match()`
    (succeeds only if the pattern matches at the start of `self.line`) to
    `re.search()` (succeeds if the pattern matches anywhere in `self.line`).
    When subclassing a `StateMachine`, list this class **first** in the
    inheritance list of the class definition.
    """

    def match(self, pattern):
        """
        Return the result of a regular expression search.

        Overrides `StateMachine.match()`.

        Parameter `pattern`: `re` compiled regular expression.
        """
        return pattern.search(self.line)


class SearchStateMachine(_SearchOverride, StateMachine):
    """`StateMachine` which uses `re.search()` instead of `re.match()`."""
    pass


class SearchStateMachineWS(_SearchOverride, StateMachineWS):
    """`StateMachineWS` which uses `re.search()` instead of `re.match()`."""
    pass


class ViewList:

    """
    List with extended functionality: slices of ViewList objects are child
    lists, linked to their parents. Changes made to a child list also affect
    the parent list.  A child list is effectively a "view" (in the SQL sense)
    of the parent list.  Changes to parent lists, however, do *not* affect
    active child lists.  If a parent list is changed, any active child lists
    should be recreated.

    The start and end of the slice can be trimmed using the `trim_start()` and
    `trim_end()` methods, without affecting the parent list.  The link between
    child and parent lists can be broken by calling `disconnect()` on the
    child list.

    Also, ViewList objects keep track of the source & offset of each item. 
    This information is accessible via the `source()`, `offset()`, and
    `info()` methods.
    """

    def __init__(self, initlist=None, source=None, items=None,
                 parent=None, parent_offset=None):
        self.data = []
        """The actual list of data, flattened from various sources."""

        self.items = []
        """A list of (source, offset) pairs, same length as `self.data`: the
        source of each line and the offset of each line from the beginning of
        its source."""

        self.parent = parent
        """The parent list."""

        self.parent_offset = parent_offset
        """Offset of this list from the beginning of the parent list."""

        if isinstance(initlist, ViewList):
            self.data = initlist.data[:]
            self.items = initlist.items[:]
        elif initlist is not None:
            self.data = list(initlist)
            if items:
                self.items = items
            else:
                self.items = [(source, i) for i in range(len(initlist))]
        assert len(self.data) == len(self.items), 'data mismatch'

    def __str__(self):
        return str(self.data)

    def __repr__(self):
        return '%s(%s, items=%s)' % (self.__class__.__name__,
                                     self.data, self.items)

    def __lt__(self, other): return self.data <  self.__cast(other)
    def __le__(self, other): return self.data <= self.__cast(other)
    def __eq__(self, other): return self.data == self.__cast(other)
    def __ne__(self, other): return self.data != self.__cast(other)
    def __gt__(self, other): return self.data >  self.__cast(other)
    def __ge__(self, other): return self.data >= self.__cast(other)
    def __cmp__(self, other): return cmp(self.data, self.__cast(other))

    def __cast(self, other):
        if isinstance(other, ViewList):
            return other.data
        else:
            return other

    def __contains__(self, item): return item in self.data
    def __len__(self): return len(self.data)

    # The __getitem__()/__setitem__() methods check whether the index
    # is a slice first, since native list objects start supporting
    # them directly in Python 2.3 (no exception is raised when
    # indexing a list with a slice object; they just work).

    def __getitem__(self, i):
        if isinstance(i, _SliceType):
            assert i.step in (None, 1),  'cannot handle slice with stride'
            return self.__class__(self.data[i.start:i.stop],
                                  items=self.items[i.start:i.stop],
                                  parent=self, parent_offset=i.start)
        else:
            return self.data[i]

    def __setitem__(self, i, item):
        if isinstance(i, _SliceType):
            assert i.step in (None, 1), 'cannot handle slice with stride'
            if not isinstance(item, ViewList):
                raise TypeError('assigning non-ViewList to ViewList slice')
            self.data[i.start:i.stop] = item.data
            self.items[i.start:i.stop] = item.items
            assert len(self.data) == len(self.items), 'data mismatch'
            if self.parent:
                self.parent[i.start + self.parent_offset
                            : i.stop + self.parent_offset] = item
        else:
            self.data[i] = item
            if self.parent:
                self.parent[i + self.parent_offset] = item

    def __delitem__(self, i):
        try:
            del self.data[i]
            del self.items[i]
            if self.parent:
                del self.parent[i + self.parent_offset]
        except TypeError:
            assert i.step is None, 'cannot handle slice with stride'
            del self.data[i.start:i.stop]
            del self.items[i.start:i.stop]
            if self.parent:
                del self.parent[i.start + self.parent_offset
                                : i.stop + self.parent_offset]

    def __add__(self, other):
        if isinstance(other, ViewList):
            return self.__class__(self.data + other.data,
                                  items=(self.items + other.items))
        else:
            raise TypeError('adding non-ViewList to a ViewList')

    def __radd__(self, other):
        if isinstance(other, ViewList):
            return self.__class__(other.data + self.data,
                                  items=(other.items + self.items))
        else:
            raise TypeError('adding ViewList to a non-ViewList')

    def __iadd__(self, other):
        if isinstance(other, ViewList):
            self.data += other.data
        else:
            raise TypeError('argument to += must be a ViewList')
        return self

    def __mul__(self, n):
        return self.__class__(self.data * n, items=(self.items * n))

    __rmul__ = __mul__

    def __imul__(self, n):
        self.data *= n
        self.items *= n
        return self

    def extend(self, other):
        if not isinstance(other, ViewList):
            raise TypeError('extending a ViewList with a non-ViewList')
        if self.parent:
            self.parent.insert(len(self.data) + self.parent_offset, other)
        self.data.extend(other.data)
        self.items.extend(other.items)

    def append(self, item, source=None, offset=0):
        if source is None:
            self.extend(item)
        else:
            if self.parent:
                self.parent.insert(len(self.data) + self.parent_offset, item,
                                   source, offset)
            self.data.append(item)
            self.items.append((source, offset))

    def insert(self, i, item, source=None, offset=0):
        if source is None:
            if not isinstance(item, ViewList):
                raise TypeError('inserting non-ViewList with no source given')
            self.data[i:i] = item.data
            self.items[i:i] = item.items
            if self.parent:
                index = (len(self.data) + i) % len(self.data)
                self.parent.insert(index + self.parent_offset, item)
        else:
            self.data.insert(i, item)
            self.items.insert(i, (source, offset))
            if self.parent:
                index = (len(self.data) + i) % len(self.data)
                self.parent.insert(index + self.parent_offset, item,
                                   source, offset)

    def pop(self, i=-1):
        if self.parent:
            index = (len(self.data) + i) % len(self.data)
            self.parent.pop(index + self.parent_offset)
        self.items.pop(i)
        return self.data.pop(i)

    def trim_start(self, n=1):
        """
        Remove items from the start of the list, without touching the parent.
        """
        if n > len(self.data):
            raise IndexError("Size of trim too large; can't trim %s items "
                             "from a list of size %s." % (n, len(self.data)))
        elif n < 0:
            raise IndexError('Trim size must be >= 0.')
        del self.data[:n]
        del self.items[:n]
        if self.parent:
            self.parent_offset += n

    def trim_end(self, n=1):
        """
        Remove items from the end of the list, without touching the parent.
        """
        if n > len(self.data):
            raise IndexError("Size of trim too large; can't trim %s items "
                             "from a list of size %s." % (n, len(self.data)))
        elif n < 0:
            raise IndexError('Trim size must be >= 0.')
        del self.data[-n:]
        del self.items[-n:]

    def remove(self, item):
        index = self.index(item)
        del self[index]

    def count(self, item): return self.data.count(item)
    def index(self, item): return self.data.index(item)

    def reverse(self):
        self.data.reverse()
        self.items.reverse()
        self.parent = None

    def sort(self, *args):
        tmp = zip(self.data, self.items)
        tmp.sort(*args)
        self.data = [entry[0] for entry in tmp]
        self.items = [entry[1] for entry in tmp]
        self.parent = None

    def info(self, i):
        """Return source & offset for index `i`."""
        try:
            return self.items[i]
        except IndexError:
            if i == len(self.data):     # Just past the end
                return self.items[i - 1][0], None
            else:
                raise

    def source(self, i):
        """Return source for index `i`."""
        return self.info(i)[0]

    def offset(self, i):
        """Return offset for index `i`."""
        return self.info(i)[1]

    def disconnect(self):
        """Break link between this list and parent list."""
        self.parent = None


class StringList(ViewList):

    """A `ViewList` with string-specific methods."""

    def trim_left(self, length, start=0, end=sys.maxint):
        """
        Trim `length` characters off the beginning of each item, in-place,
        from index `start` to `end`.  No whitespace-checking is done on the
        trimmed text.  Does not affect slice parent.
        """
        self.data[start:end] = [line[length:]
                                for line in self.data[start:end]]

    def get_text_block(self, start, flush_left=0):
        """
        Return a contiguous block of text.

        If `flush_left` is true, raise `UnexpectedIndentationError` if an
        indented line is encountered before the text block ends (with a blank
        line).
        """
        end = start
        last = len(self.data)
        while end < last:
            line = self.data[end]
            if not line.strip():
                break
            if flush_left and (line[0] == ' '):
                source, offset = self.info(end)
                raise UnexpectedIndentationError(self[start:end], source,
                                                 offset + 1)
            end += 1
        return self[start:end]

    def get_indented(self, start=0, until_blank=0, strip_indent=1,
                     block_indent=None, first_indent=None):
        """
        Extract and return a StringList of indented lines of text.

        Collect all lines with indentation, determine the minimum indentation,
        remove the minimum indentation from all indented lines (unless
        `strip_indent` is false), and return them. All lines up to but not
        including the first unindented line will be returned.

        :Parameters:
          - `start`: The index of the first line to examine.
          - `until_blank`: Stop collecting at the first blank line if true.
          - `strip_indent`: Strip common leading indent if true (default).
          - `block_indent`: The indent of the entire block, if known.
          - `first_indent`: The indent of the first line, if known.

        :Return:
          - a StringList of indented lines with mininum indent removed;
          - the amount of the indent;
          - a boolean: did the indented block finish with a blank line or EOF?
        """
        indent = block_indent           # start with None if unknown
        end = start
        if block_indent is not None and first_indent is None:
            first_indent = block_indent
        if first_indent is not None:
            end += 1
        last = len(self.data)
        while end < last:
            line = self.data[end]
            if line and (line[0] != ' '
                         or (block_indent is not None
                             and line[:block_indent].strip())):
                # Line not indented or insufficiently indented.
                # Block finished properly iff the last indented line blank:
                blank_finish = ((end > start)
                                and not self.data[end - 1].strip())
                break
            stripped = line.lstrip()
            if not stripped:            # blank line
                if until_blank:
                    blank_finish = 1
                    break
            elif block_indent is None:
                line_indent = len(line) - len(stripped)
                if indent is None:
                    indent = line_indent
                else:
                    indent = min(indent, line_indent)
            end += 1
        else:
            blank_finish = 1            # block ends at end of lines
        block = self[start:end]
        if first_indent is not None and block:
            block.data[0] = block.data[0][first_indent:]
        if indent and strip_indent:
            block.trim_left(indent, start=(first_indent is not None))
        return block, indent or 0, blank_finish

    def get_2D_block(self, top, left, bottom, right, strip_indent=1):
        block = self[top:bottom]
        indent = right
        for i in range(len(block.data)):
            block.data[i] = line = block.data[i][left:right].rstrip()
            if line:
                indent = min(indent, len(line) - len(line.lstrip()))
        if strip_indent and 0 < indent < right:
            block.data = [line[indent:] for line in block.data]
        return block


class StateMachineError(Exception): pass
class UnknownStateError(StateMachineError): pass
class DuplicateStateError(StateMachineError): pass
class UnknownTransitionError(StateMachineError): pass
class DuplicateTransitionError(StateMachineError): pass
class TransitionPatternNotFound(StateMachineError): pass
class TransitionMethodNotFound(StateMachineError): pass
class UnexpectedIndentationError(StateMachineError): pass


class TransitionCorrection(Exception):

    """
    Raise from within a transition method to switch to another transition.

    Raise with one argument, the new transition name.
    """


class StateCorrection(Exception):

    """
    Raise from within a transition method to switch to another state.

    Raise with one or two arguments: new state name, and an optional new
    transition name.
    """


def string2lines(astring, tab_width=8, convert_whitespace=0,
                 whitespace=re.compile('[\v\f]')):
    """
    Return a list of one-line strings with tabs expanded and no newlines.

    Each tab is expanded with between 1 and `tab_width` spaces, so that the
    next character's index becomes a multiple of `tab_width` (8 by default).

    Parameters:

    - `astring`: a multi-line string.
    - `tab_width`: the number of columns between tab stops.
    - `convert_whitespace`: convert form feeds and vertical tabs to spaces?
    """
    if convert_whitespace:
        astring = whitespace.sub(' ', astring)
    return [s.expandtabs(tab_width) for s in astring.splitlines()]

def _exception_data():
    """
    Return exception information:

    - the exception's class name;
    - the exception object;
    - the name of the file containing the offending code;
    - the line number of the offending code;
    - the function name of the offending code.
    """
    type, value, traceback = sys.exc_info()
    while traceback.tb_next:
        traceback = traceback.tb_next
    code = traceback.tb_frame.f_code
    return (type.__name__, value, code.co_filename, traceback.tb_lineno,
            code.co_name)
Zope-2.9.4-retire_zpkg/lib/python/docutils/COPYING.txt0000644000175000017500000001167110172235404022464 0ustar  tseavertseaver==================
 Copying Docutils
==================

:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2005/01/07 15:11:43 $
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.

Most of the files included in this project have been placed in the
public domain, and therefore have no license requirements and no
restrictions on copying or usage; see the `Public Domain Dedication`_
below.  There are a few exceptions_, listed below.

One goal of the Docutils project is to be included in the Python
standard library distribution, at which time it is expected that
copyright will be asserted by the `Python Software Foundation
`_.


Public Domain Dedication
========================

The persons who have associated their work with this project (the
"Dedicator": David Goodger and the many contributors to the Docutils
project) hereby dedicate the entire copyright, less the exceptions_
listed below, in the work of authorship known as "Docutils" identified
below (the "Work") to the public domain.

The primary repository for the Work is the Internet World Wide Web
site .  The Work consists of the
files within the "docutils" module of the Docutils project CVS
repository (Internet host cvs.sourceforge.net, filesystem path
/cvsroot/docutils), whose Internet web interface is located at
.
Files dedicated to the public domain may be identified by the
inclusion, near the beginning of each file, of a declaration of the
form::

    Copyright: This document/module/DTD/stylesheet/file/etc. has been
               placed in the public domain.

Dedicator makes this dedication for the benefit of the public at large
and to the detriment of Dedicator's heirs and successors.  Dedicator
intends this dedication to be an overt act of relinquishment in
perpetuity of all present and future rights under copyright law,
whether vested or contingent, in the Work.  Dedicator understands that
such relinquishment of all rights includes the relinquishment of all
rights to enforce (by lawsuit or otherwise) those copyrights in the
Work.

Dedicator recognizes that, once placed in the public domain, the Work
may be freely reproduced, distributed, transmitted, used, modified,
built upon, or otherwise exploited by anyone for any purpose,
commercial or non-commercial, and in any way, including by methods
that have not yet been invented or conceived.

(This dedication is derived from the text of the `Creative Commons
Public Domain Dedication
`_.)


Exceptions
==========

The exceptions to the `Public Domain Dedication`_ above are:

* extras/optparse.py, copyright by Gregory P. Ward, released under a
  BSD-style license (which can be found in the module's source code).

* extras/textwrap.py, copyright by Gregory P. Ward and the Python
  Software Foundation, released under the `Python 2.3 license`_
  (`local copy`__).

  __ licenses/python-2-3.txt

* extras/roman.py, copyright by Mark Pilgrim, released under the
  `Python 2.1.1 license`_ (`local copy`__).

  __ licenses/python-2-1-1.txt

* test/docutils_difflib.py, copyright by the Python Software
  Foundation, released under the `Python 2.2 license`_ (`local
  copy`__).  This file is included for compatibility with Python
  versions less than 2.2.  (It's only used to report test failures
  anyhow; it isn't installed anywhere.  The included file is a
  pre-generator version of the difflib.py module included in Python
  2.2.)

  __ licenses/python-2-2.txt

* tools/pep2html.py, copyright by the Python Software Foundation,
  released under the `Python 2.2 license`_ (`local copy`__).

  __ licenses/python-2-2.txt

* tools/editors/emacs/rst-html.el, copyright by Martin Blais, released
  under the `GNU General Public License`_ (`local copy`__).

  __ licenses/gpl.txt

* tools/editors/emacs/rst-mode.el, copyright by Stefan Merten,
  released under the `GNU General Public License`_ (`local copy`__).

  __ licenses/gpl.txt

(Disclaimer: I am not a lawyer.)  The BSD license and the Python
licenses are OSI-approved_ and GPL-compatible_.  Although complicated
by multiple owners and lots of legalese, the Python license basically
lets you copy, use, modify, and redistribute files as long as you keep
the copyright attribution intact, note any changes you make, and don't
use the owner's name in vain.  The BSD license is similar.

Plaintext versions of all the linked-to licenses are provided in the
licenses_ directory.

.. _licenses: licenses/
.. _Python 2.1.1 license: http://www.python.org/2.1.1/license.html
.. _Python 2.2 license: http://www.python.org/2.2/license.html
.. _Python 2.3 license: http://www.python.org/2.3/license.html
.. _GNU General Public License: http://www.gnu.org/copyleft/gpl.html
.. _OSI-approved: http://opensource.org/licenses/
.. _GPL-compatible: http://www.gnu.org/philosophy/license-list.html
Zope-2.9.4-retire_zpkg/lib/python/docutils/utils.py0000644000175000017500000004636310322224711022327 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3253 $
# Date: $Date: 2005-04-25 17:08:01 +0200 (Mon, 25 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
Miscellaneous utilities for the documentation utilities.
"""

__docformat__ = 'reStructuredText'

import sys
import os
import os.path
import warnings
from types import StringType, UnicodeType
from docutils import ApplicationError, DataError
from docutils import frontend, nodes


class SystemMessage(ApplicationError):

    def __init__(self, system_message, level):
        Exception.__init__(self, system_message.astext())
        self.level = level


class SystemMessagePropagation(ApplicationError): pass


class Reporter:

    """
    Info/warning/error reporter and ``system_message`` element generator.

    Five levels of system messages are defined, along with corresponding
    methods: `debug()`, `info()`, `warning()`, `error()`, and `severe()`.

    There is typically one Reporter object per process.  A Reporter object is
    instantiated with thresholds for reporting (generating warnings) and
    halting processing (raising exceptions), a switch to turn debug output on
    or off, and an I/O stream for warnings.  These are stored as instance
    attributes.

    When a system message is generated, its level is compared to the stored
    thresholds, and a warning or error is generated as appropriate.  Debug
    messages are produced iff the stored debug switch is on, independently of
    other thresholds.  Message output is sent to the stored warning stream if
    not set to ''.

    The Reporter class also employs a modified form of the "Observer" pattern
    [GoF95]_ to track system messages generated.  The `attach_observer` method
    should be called before parsing, with a bound method or function which
    accepts system messages.  The observer can be removed with
    `detach_observer`, and another added in its place.

    .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of
       Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA,
       1995.
    """

    levels = 'DEBUG INFO WARNING ERROR SEVERE'.split()
    """List of names for system message levels, indexed by level."""

    def __init__(self, source, report_level, halt_level, stream=None,
                 debug=0, encoding='ascii', error_handler='replace'):
        """
        :Parameters:
            - `source`: The path to or description of the source data.
            - `report_level`: The level at or above which warning output will
              be sent to `stream`.
            - `halt_level`: The level at or above which `SystemMessage`
              exceptions will be raised, halting execution.
            - `debug`: Show debug (level=0) system messages?
            - `stream`: Where warning output is sent.  Can be file-like (has a
              ``.write`` method), a string (file name, opened for writing),
              '' (empty string, for discarding all stream messages) or
              `None` (implies `sys.stderr`; default).
            - `encoding`: The encoding for stderr output.
            - `error_handler`: The error handler for stderr output encoding.
        """
        self.source = source
        """The path to or description of the source data."""

        self.encoding = encoding
        """The character encoding for the stderr output."""

        self.error_handler = error_handler
        """The character encoding error handler."""

        self.debug_flag = debug
        """Show debug (level=0) system messages?"""

        self.report_level = report_level
        """The level at or above which warning output will be sent
        to `self.stream`."""

        self.halt_level = halt_level
        """The level at or above which `SystemMessage` exceptions
        will be raised, halting execution."""

        if stream is None:
            stream = sys.stderr
        elif type(stream) in (StringType, UnicodeType):
            # Leave stream untouched if it's ''.
            if stream != '':
                if type(stream) == StringType:
                    stream = open(stream, 'w')
                elif type(stream) == UnicodeType:
                    stream = open(stream.encode(), 'w')

        self.stream = stream
        """Where warning output is sent."""

        self.observers = []
        """List of bound methods or functions to call with each system_message
        created."""

        self.max_level = -1
        """The highest level system message generated so far."""

    def set_conditions(self, category, report_level, halt_level,
                       stream=None, debug=0):
        warnings.warn('docutils.utils.Reporter.set_conditions deprecated; '
                      'set attributes via configuration settings or directly',
                      DeprecationWarning, stacklevel=2)
        self.report_level = report_level
        self.halt_level = halt_level
        if stream is None:
            stream = sys.stderr
        self.stream = stream
        self.debug = debug

    def attach_observer(self, observer):
        """
        The `observer` parameter is a function or bound method which takes one
        argument, a `nodes.system_message` instance.
        """
        self.observers.append(observer)

    def detach_observer(self, observer):
        self.observers.remove(observer)

    def notify_observers(self, message):
        for observer in self.observers:
            observer(message)

    def system_message(self, level, message, *children, **kwargs):
        """
        Return a system_message object.

        Raise an exception or generate a warning if appropriate.
        """
        attributes = kwargs.copy()
        if kwargs.has_key('base_node'):
            source, line = get_source_line(kwargs['base_node'])
            del attributes['base_node']
            if source is not None:
                attributes.setdefault('source', source)
            if line is not None:
                attributes.setdefault('line', line)
        attributes.setdefault('source', self.source)
        msg = nodes.system_message(message, level=level,
                                   type=self.levels[level],
                                   *children, **attributes)
        if self.stream and (level >= self.report_level
                            or self.debug_flag and level == 0):
            msgtext = msg.astext().encode(self.encoding, self.error_handler)
            print >>self.stream, msgtext
        if level >= self.halt_level:
            raise SystemMessage(msg, level)
        if level > 0 or self.debug_flag:
            self.notify_observers(msg)
        self.max_level = max(level, self.max_level)
        return msg

    def debug(self, *args, **kwargs):
        """
        Level-0, "DEBUG": an internal reporting issue. Typically, there is no
        effect on the processing. Level-0 system messages are handled
        separately from the others.
        """
        if self.debug_flag:
            return self.system_message(0, *args, **kwargs)

    def info(self, *args, **kwargs):
        """
        Level-1, "INFO": a minor issue that can be ignored. Typically there is
        no effect on processing, and level-1 system messages are not reported.
        """
        return self.system_message(1, *args, **kwargs)

    def warning(self, *args, **kwargs):
        """
        Level-2, "WARNING": an issue that should be addressed. If ignored,
        there may be unpredictable problems with the output.
        """
        return self.system_message(2, *args, **kwargs)

    def error(self, *args, **kwargs):
        """
        Level-3, "ERROR": an error that should be addressed. If ignored, the
        output will contain errors.
        """
        return self.system_message(3, *args, **kwargs)

    def severe(self, *args, **kwargs):
        """
        Level-4, "SEVERE": a severe error that must be addressed. If ignored,
        the output will contain severe errors. Typically level-4 system
        messages are turned into exceptions which halt processing.
        """
        return self.system_message(4, *args, **kwargs)


class ExtensionOptionError(DataError): pass
class BadOptionError(ExtensionOptionError): pass
class BadOptionDataError(ExtensionOptionError): pass
class DuplicateOptionError(ExtensionOptionError): pass


def extract_extension_options(field_list, options_spec):
    """
    Return a dictionary mapping extension option names to converted values.

    :Parameters:
        - `field_list`: A flat field list without field arguments, where each
          field body consists of a single paragraph only.
        - `options_spec`: Dictionary mapping known option names to a
          conversion function such as `int` or `float`.

    :Exceptions:
        - `KeyError` for unknown option names.
        - `ValueError` for invalid option values (raised by the conversion
           function).
        - `TypeError` for invalid option value types (raised by conversion
           function).
        - `DuplicateOptionError` for duplicate options.
        - `BadOptionError` for invalid fields.
        - `BadOptionDataError` for invalid option data (missing name,
          missing data, bad quotes, etc.).
    """
    option_list = extract_options(field_list)
    option_dict = assemble_option_dict(option_list, options_spec)
    return option_dict

def extract_options(field_list):
    """
    Return a list of option (name, value) pairs from field names & bodies.

    :Parameter:
        `field_list`: A flat field list, where each field name is a single
        word and each field body consists of a single paragraph only.

    :Exceptions:
        - `BadOptionError` for invalid fields.
        - `BadOptionDataError` for invalid option data (missing name,
          missing data, bad quotes, etc.).
    """
    option_list = []
    for field in field_list:
        if len(field[0].astext().split()) != 1:
            raise BadOptionError(
                'extension option field name may not contain multiple words')
        name = str(field[0].astext().lower())
        body = field[1]
        if len(body) == 0:
            data = None
        elif len(body) > 1 or not isinstance(body[0], nodes.paragraph) \
              or len(body[0]) != 1 or not isinstance(body[0][0], nodes.Text):
            raise BadOptionDataError(
                  'extension option field body may contain\n'
                  'a single paragraph only (option "%s")' % name)
        else:
            data = body[0][0].astext()
        option_list.append((name, data))
    return option_list

def assemble_option_dict(option_list, options_spec):
    """
    Return a mapping of option names to values.

    :Parameters:
        - `option_list`: A list of (name, value) pairs (the output of
          `extract_options()`).
        - `options_spec`: Dictionary mapping known option names to a
          conversion function such as `int` or `float`.

    :Exceptions:
        - `KeyError` for unknown option names.
        - `DuplicateOptionError` for duplicate options.
        - `ValueError` for invalid option values (raised by conversion
           function).
        - `TypeError` for invalid option value types (raised by conversion
           function).
    """
    options = {}
    for name, value in option_list:
        convertor = options_spec[name]  # raises KeyError if unknown
        if convertor is None:
            raise KeyError(name)        # or if explicitly disabled
        if options.has_key(name):
            raise DuplicateOptionError('duplicate option "%s"' % name)
        try:
            options[name] = convertor(value)
        except (ValueError, TypeError), detail:
            raise detail.__class__('(option: "%s"; value: %r)\n%s'
                                   % (name, value, ' '.join(detail.args)))
    return options


class NameValueError(DataError): pass


def extract_name_value(line):
    """
    Return a list of (name, value) from a line of the form "name=value ...".

    :Exception:
        `NameValueError` for invalid input (missing name, missing data, bad
        quotes, etc.).
    """
    attlist = []
    while line:
        equals = line.find('=')
        if equals == -1:
            raise NameValueError('missing "="')
        attname = line[:equals].strip()
        if equals == 0 or not attname:
            raise NameValueError(
                  'missing attribute name before "="')
        line = line[equals+1:].lstrip()
        if not line:
            raise NameValueError(
                  'missing value after "%s="' % attname)
        if line[0] in '\'"':
            endquote = line.find(line[0], 1)
            if endquote == -1:
                raise NameValueError(
                      'attribute "%s" missing end quote (%s)'
                      % (attname, line[0]))
            if len(line) > endquote + 1 and line[endquote + 1].strip():
                raise NameValueError(
                      'attribute "%s" end quote (%s) not followed by '
                      'whitespace' % (attname, line[0]))
            data = line[1:endquote]
            line = line[endquote+1:].lstrip()
        else:
            space = line.find(' ')
            if space == -1:
                data = line
                line = ''
            else:
                data = line[:space]
                line = line[space+1:].lstrip()
        attlist.append((attname.lower(), data))
    return attlist

def new_document(source, settings=None):
    """
    Return a new empty document object.

    :Parameters:
        `source` : string
            The path to or description of the source text of the document.
        `settings` : optparse.Values object
            Runtime settings.  If none provided, a default set will be used.
    """
    if settings is None:
        settings = frontend.OptionParser().get_default_values()
    reporter = Reporter(source, settings.report_level, settings.halt_level,
                        stream=settings.warning_stream, debug=settings.debug,
                        encoding=settings.error_encoding,
                        error_handler=settings.error_encoding_error_handler)
    document = nodes.document(settings, reporter, source=source)
    document.note_source(source, -1)
    return document

def clean_rcs_keywords(paragraph, keyword_substitutions):
    if len(paragraph) == 1 and isinstance(paragraph[0], nodes.Text):
        textnode = paragraph[0]
        for pattern, substitution in keyword_substitutions:
            match = pattern.search(textnode.data)
            if match:
                textnode.data = pattern.sub(substitution, textnode.data)
                return

def relative_path(source, target):
    """
    Build and return a path to `target`, relative to `source` (both files).

    If there is no common prefix, return the absolute path to `target`.
    """
    source_parts = os.path.abspath(source or 'dummy_file').split(os.sep)
    target_parts = os.path.abspath(target).split(os.sep)
    # Check first 2 parts because '/dir'.split('/') == ['', 'dir']:
    if source_parts[:2] != target_parts[:2]:
        # Nothing in common between paths.
        # Return absolute path, using '/' for URLs:
        return '/'.join(target_parts)
    source_parts.reverse()
    target_parts.reverse()
    while (source_parts and target_parts
           and source_parts[-1] == target_parts[-1]):
        # Remove path components in common:
        source_parts.pop()
        target_parts.pop()
    target_parts.reverse()
    parts = ['..'] * (len(source_parts) - 1) + target_parts
    return '/'.join(parts)

def get_stylesheet_reference(settings, relative_to=None):
    """
    Retrieve a stylesheet reference from the settings object.
    """
    if settings.stylesheet_path:
        assert not settings.stylesheet, \
               'stylesheet and stylesheet_path are mutually exclusive.'
        if relative_to == None:
            relative_to = settings._destination
        return relative_path(relative_to, settings.stylesheet_path)
    else:
        return settings.stylesheet

def get_trim_footnote_ref_space(settings):
    """
    Return whether or not to trim footnote space.

    If trim_footnote_reference_space is not None, return it.

    If trim_footnote_reference_space is None, return False unless the
    footnote reference style is 'superscript'.
    """
    if settings.trim_footnote_reference_space is None:
        return hasattr(settings, 'footnote_references') and \
               settings.footnote_references == 'superscript'
    else:
        return settings.trim_footnote_reference_space

def get_source_line(node):
    """
    Return the "source" and "line" attributes from the `node` given or from
    its closest ancestor.
    """
    while node:
        if node.source or node.line:
            return node.source, node.line
        node = node.parent
    return None, None

def escape2null(text):
    """Return a string with escape-backslashes converted to nulls."""
    parts = []
    start = 0
    while 1:
        found = text.find('\\', start)
        if found == -1:
            parts.append(text[start:])
            return ''.join(parts)
        parts.append(text[start:found])
        parts.append('\x00' + text[found+1:found+2])
        start = found + 2               # skip character after escape

def unescape(text, restore_backslashes=0):
    """
    Return a string with nulls removed or restored to backslashes.
    Backslash-escaped spaces are also removed.
    """
    if restore_backslashes:
        return text.replace('\x00', '\\')
    else:
        for sep in ['\x00 ', '\x00\n', '\x00']:
            text = ''.join(text.split(sep))
        return text


class DependencyList:

    """
    List of dependencies, with file recording support.

    Note that the output file is not automatically closed.  You have
    to explicitly call the close() method.
    """

    def __init__(self, output_file=None, dependencies=[]):
        """
        Initialize the dependency list, automatically setting the
        output file to `output_file` (see `set_output()`) and adding
        all supplied dependencies.
        """
        self.set_output(output_file)
        for i in dependencies:
            self.add(i)

    def set_output(self, output_file):
        """
        Set the output file and clear the list of already added
        dependencies.

        `output_file` must be a string.  The specified file is
        immediately overwritten.

        If output_file is '-', the output will be written to stdout.
        If it is None, no file output is done when calling add().
        """
        self.list = []
        if output_file == '-':
            self.file = sys.stdout
        elif output_file:
            self.file = open(output_file, 'w')
        else:
            self.file = None

    def add(self, filename):
        """
        If the dependency `filename` has not already been added,
        append it to self.list and print it to self.file if self.file
        is not None.
        """
        if not filename in self.list:
            self.list.append(filename)
            if self.file is not None:
                print >>self.file, filename

    def close(self):
        """
        Close the output file.
        """
        self.file.close()
        self.file = None

    def __repr__(self):
        if self.file:
            output_file = self.file.name
        else:
            output_file = None
        return '%s(%r, %s)' % (self.__class__.__name__, output_file, self.list)
Zope-2.9.4-retire_zpkg/lib/python/docutils/transforms/0000755000175000017500000000000010447233610023005 5ustar  tseavertseaverZope-2.9.4-retire_zpkg/lib/python/docutils/transforms/references.py0000644000175000017500000007455210322224711025507 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3149 $
# Date: $Date: 2005-03-30 22:51:06 +0200 (Wed, 30 Mar 2005) $
# Copyright: This module has been placed in the public domain.

"""
Transforms for resolving references.
"""

__docformat__ = 'reStructuredText'

import sys
import re
from docutils import nodes, utils
from docutils.transforms import TransformError, Transform


class PropagateTargets(Transform):

    """
    Propagate empty internal targets to the next element.

    Given the following nodes::

        
        
        
        
            This is a test.

    PropagateTargets propagates the ids and names of the internal
    targets preceding the paragraph to the paragraph itself::

        
        
        
        
            This is a test.
    """

    default_priority = 260

    def apply(self):
        for target in self.document.internal_targets:
            if not (len(target) == 0 and
                    not (target.attributes.has_key('refid') or
                         target.attributes.has_key('refuri') or
                         target.attributes.has_key('refname'))):
                continue
            next_node = target.next_node(ascend=1)
            # Do not move names and ids into Invisibles (we'd lose the
            # attributes) or different Targetables (e.g. footnotes).
            if (next_node is not None and
                ((not isinstance(next_node, nodes.Invisible) and
                  not isinstance(next_node, nodes.Targetable)) or
                 isinstance(next_node, nodes.target))):
                next_node['ids'].extend(target['ids'])
                next_node['names'].extend(target['names'])
                # Set defaults for next_node.expect_referenced_by_name/id.
                if not hasattr(next_node, 'expect_referenced_by_name'):
                    next_node.expect_referenced_by_name = {}
                if not hasattr(next_node, 'expect_referenced_by_id'):
                    next_node.expect_referenced_by_id = {}
                for id in target['ids']:
                    # Update IDs to node mapping.
                    self.document.ids[id] = next_node
                    # If next_node is referenced by id ``id``, this
                    # target shall be marked as referenced.
                    next_node.expect_referenced_by_id[id] = target
                for name in target['names']:
                    next_node.expect_referenced_by_name[name] = target
                # If there are any expect_referenced_by_... attributes
                # in target set, copy them to next_node.
                next_node.expect_referenced_by_name.update(
                    getattr(target, 'expect_referenced_by_name', {}))
                next_node.expect_referenced_by_id.update(
                    getattr(target, 'expect_referenced_by_id', {}))
                # Set refid to point to the first former ID of target
                # which is now an ID of next_node.
                target['refid'] = target['ids'][0]
                # Clear ids and names; they have been moved to
                # next_node.
                target['ids'] = []
                target['names'] = []
                self.document.note_refid(target)
                self.document.note_internal_target(next_node)


class AnonymousHyperlinks(Transform):

    """
    Link anonymous references to targets.  Given::

        
            
                internal
            
                external
        
        

    Corresponding references are linked via "refid" or resolved via "refuri"::

        
            
                text
            
                external
        
        
    """

    default_priority = 440

    def apply(self):
        if len(self.document.anonymous_refs) \
              != len(self.document.anonymous_targets):
            msg = self.document.reporter.error(
                  'Anonymous hyperlink mismatch: %s references but %s '
                  'targets.\nSee "backrefs" attribute for IDs.'
                  % (len(self.document.anonymous_refs),
                     len(self.document.anonymous_targets)))
            msgid = self.document.set_id(msg)
            for ref in self.document.anonymous_refs:
                prb = nodes.problematic(
                      ref.rawsource, ref.rawsource, refid=msgid)
                prbid = self.document.set_id(prb)
                msg.add_backref(prbid)
                ref.parent.replace(ref, prb)
            for target in self.document.anonymous_targets:
                # Assume that all anonymous targets have been
                # referenced to avoid generating lots of
                # system_messages.
                target.referenced = 1
            return
        for ref, target in zip(self.document.anonymous_refs,
                               self.document.anonymous_targets):
            target.referenced = 1
            while 1:
                if target.hasattr('refuri'):
                    ref['refuri'] = target['refuri']
                    ref.resolved = 1
                    break
                else:
                    if not target['ids']:
                        # Propagated target.
                        target = self.document.ids[target['refid']]
                        continue
                    ref['refid'] = target['ids'][0]
                    self.document.note_refid(ref)
                    break


class IndirectHyperlinks(Transform):

    """
    a) Indirect external references::

           
               
                   indirect external
           
           

       The "refuri" attribute is migrated back to all indirect targets
       from the final direct target (i.e. a target not referring to
       another indirect target)::

           
               
                   indirect external
           
           

       Once the attribute is migrated, the preexisting "refname" attribute
       is dropped.

    b) Indirect internal references::

           
           
               
                   indirect internal
           
           

       Targets which indirectly refer to an internal target become one-hop
       indirect (their "refid" attributes are directly set to the internal
       target's "id"). References which indirectly refer to an internal
       target become direct internal references::

           
           
               
                   indirect internal
           
           
    """

    default_priority = 460

    def apply(self):
        for target in self.document.indirect_targets:
            if not target.resolved:
                self.resolve_indirect_target(target)
            self.resolve_indirect_references(target)

    def resolve_indirect_target(self, target):
        refname = target.get('refname')
        if refname is None:
            reftarget_id = target['refid']
        else:
            reftarget_id = self.document.nameids.get(refname)
            if not reftarget_id:
                # Check the unknown_reference_resolvers
                for resolver_function in \
                        self.document.transformer.unknown_reference_resolvers:
                    if resolver_function(target):
                        break
                else:
                    self.nonexistent_indirect_target(target)
                return
        reftarget = self.document.ids[reftarget_id]
        reftarget.note_referenced_by(id=reftarget_id)
        if isinstance(reftarget, nodes.target) \
               and not reftarget.resolved and reftarget.hasattr('refname'):
            if hasattr(target, 'multiply_indirect'):
                #and target.multiply_indirect):
                #del target.multiply_indirect
                self.circular_indirect_reference(target)
                return
            target.multiply_indirect = 1
            self.resolve_indirect_target(reftarget) # multiply indirect
            del target.multiply_indirect
        if reftarget.hasattr('refuri'):
            target['refuri'] = reftarget['refuri']
            if target['names']:
                self.document.note_external_target(target)
            if target.has_key('refid'):
                del target['refid']
        elif reftarget.hasattr('refid'):
            target['refid'] = reftarget['refid']
            self.document.note_refid(target)
        else:
            if reftarget['ids']:
                target['refid'] = reftarget_id
                self.document.note_refid(target)
            else:
                self.nonexistent_indirect_target(target)
                return
        if refname is not None:
            del target['refname']
        target.resolved = 1

    def nonexistent_indirect_target(self, target):
        if self.document.nameids.has_key(target['refname']):
            self.indirect_target_error(target, 'which is a duplicate, and '
                                       'cannot be used as a unique reference')
        else:
            self.indirect_target_error(target, 'which does not exist')

    def circular_indirect_reference(self, target):
        self.indirect_target_error(target, 'forming a circular reference')

    def indirect_target_error(self, target, explanation):
        naming = ''
        reflist = []
        if target['names']:
            naming = '"%s" ' % target['names'][0]
        for name in target['names']:
            reflist.extend(self.document.refnames.get(name, []))
        for id in target['ids']:
            reflist.extend(self.document.refids.get(id, []))
        naming += '(id="%s")' % target['ids'][0]
        msg = self.document.reporter.error(
              'Indirect hyperlink target %s refers to target "%s", %s.'
              % (naming, target['refname'], explanation), base_node=target)
        msgid = self.document.set_id(msg)
        for ref in uniq(reflist):
            prb = nodes.problematic(
                  ref.rawsource, ref.rawsource, refid=msgid)
            prbid = self.document.set_id(prb)
            msg.add_backref(prbid)
            ref.parent.replace(ref, prb)
        target.resolved = 1

    def resolve_indirect_references(self, target):
        if target.hasattr('refid'):
            attname = 'refid'
            call_if_named = 0
            call_method = self.document.note_refid
        elif target.hasattr('refuri'):
            attname = 'refuri'
            call_if_named = 1
            call_method = self.document.note_external_target
        else:
            return
        attval = target[attname]
        for name in target['names']:
            reflist = self.document.refnames.get(name, [])
            if reflist:
                target.note_referenced_by(name=name)
            for ref in reflist:
                if ref.resolved:
                    continue
                del ref['refname']
                ref[attname] = attval
                if not call_if_named or ref['names']:
                    call_method(ref)
                ref.resolved = 1
                if isinstance(ref, nodes.target):
                    self.resolve_indirect_references(ref)
        for id in target['ids']:
            reflist = self.document.refids.get(id, [])
            if reflist:
                target.note_referenced_by(id=id)
            for ref in reflist:
                if ref.resolved:
                    continue
                del ref['refid']
                ref[attname] = attval
                if not call_if_named or ref['names']:
                    call_method(ref)
                ref.resolved = 1
                if isinstance(ref, nodes.target):
                    self.resolve_indirect_references(ref)


class ExternalTargets(Transform):

    """
    Given::

        
            
                direct external
        

    The "refname" attribute is replaced by the direct "refuri" attribute::

        
            
                direct external
        
    """

    default_priority = 640

    def apply(self):
        for target in self.document.external_targets:
            if target.hasattr('refuri'):
                refuri = target['refuri']
                for name in target['names']:
                    reflist = self.document.refnames.get(name, [])
                    if reflist:
                        target.note_referenced_by(name=name)
                    for ref in reflist:
                        if ref.resolved:
                            continue
                        del ref['refname']
                        ref['refuri'] = refuri
                        ref.resolved = 1


class InternalTargets(Transform):

    default_priority = 660

    def apply(self):
        for target in self.document.internal_targets:
            self.resolve_reference_ids(target)

    def resolve_reference_ids(self, target):
        """
        Given::

            
                
                    direct internal
            

        The "refname" attribute is replaced by "refid" linking to the target's
        "id"::

            
                
                    direct internal
            
        """
        if target.hasattr('refuri') or target.hasattr('refid') \
              or not target['names']:
            return
        for name in target['names']:
            refid = self.document.nameids[name]
            reflist = self.document.refnames.get(name, [])
            if reflist:
                target.note_referenced_by(name=name)
            for ref in reflist:
                if ref.resolved:
                    continue
                del ref['refname']
                ref['refid'] = refid
                ref.resolved = 1


class Footnotes(Transform):

    """
    Assign numbers to autonumbered footnotes, and resolve links to footnotes,
    citations, and their references.

    Given the following ``document`` as input::

        
            
                A labeled autonumbered footnote referece:
                
            
                An unlabeled autonumbered footnote referece:
                
            
                
                    Unlabeled autonumbered footnote.
            
                
                    Labeled autonumbered footnote.

    Auto-numbered footnotes have attribute ``auto="1"`` and no label.
    Auto-numbered footnote_references have no reference text (they're
    empty elements). When resolving the numbering, a ``label`` element
    is added to the beginning of the ``footnote``, and reference text
    to the ``footnote_reference``.

    The transformed result will be::

        
            
                A labeled autonumbered footnote referece:
                
                    2
            
                An unlabeled autonumbered footnote referece:
                
                    1
            
                
\n')
        # skip content-type meta tag with interpolated charset value:
        self.html_head.extend(self.head[1:])
        self.html_body.extend(self.body_prefix[1:] + self.body_pre_docinfo
                              + self.docinfo + self.body
                              + self.body_suffix[:-1])

    def visit_emphasis(self, node):
        self.body.append('')

    def depart_emphasis(self, node):
        self.body.append('')

    def visit_entry(self, node):
        atts = {'class': []}
        if isinstance(node.parent.parent, nodes.thead):
            atts['class'].append('head')
        if node.parent.parent.parent.stubs[node.parent.column]:
            # "stubs" list is an attribute of the tgroup element
            atts['class'].append('stub')
        if atts['class']:
            tagname = 'th'
            atts['class'] = ' '.join(atts['class'])
        else:
            tagname = 'td'
            del atts['class']
        node.parent.column += 1
        if node.has_key('morerows'):
            atts['rowspan'] = node['morerows'] + 1
        if node.has_key('morecols'):
            atts['colspan'] = node['morecols'] + 1
            node.parent.column += node['morecols']
        self.body.append(self.starttag(node, tagname, '', **atts))
        self.context.append('\n' % tagname.lower())
        if len(node) == 0:              # empty cell
            self.body.append(' ')
        self.set_first_last(node)

    def depart_entry(self, node):
        self.body.append(self.context.pop())

    def visit_enumerated_list(self, node):
        """
        The 'start' attribute does not conform to HTML 4.01's strict.dtd, but
        CSS1 doesn't help. CSS2 isn't widely enough supported yet to be
        usable.
        """
        atts = {}
        if node.has_key('start'):
            atts['start'] = node['start']
        if node.has_key('enumtype'):
            atts['class'] = node['enumtype']
        # @@@ To do: prefix, suffix. How? Change prefix/suffix to a
        # single "format" attribute? Use CSS2?
        old_compact_simple = self.compact_simple
        self.context.append((self.compact_simple, self.compact_p))
        self.compact_p = None
        self.compact_simple = (self.settings.compact_lists and
                               (self.compact_simple
                                or self.topic_classes == ['contents']
                                or self.check_simple_list(node)))
        if self.compact_simple and not old_compact_simple:
            atts['class'] = (atts.get('class', '') + ' simple').strip()
        self.body.append(self.starttag(node, 'ol', **atts))

    def depart_enumerated_list(self, node):
        self.compact_simple, self.compact_p = self.context.pop()
        self.body.append('\n')

    def visit_error(self, node):
        self.visit_admonition(node, 'error')

    def depart_error(self, node):
        self.depart_admonition()

    def visit_field(self, node):
        self.body.append(self.starttag(node, 'tr', '', CLASS='field'))

    def depart_field(self, node):
        self.body.append('
\n')

    def visit_field_name(self, node):
        atts = {}
        if self.in_docinfo:
            atts['class'] = 'docinfo-name'
        else:
            atts['class'] = 'field-name'
        if ( self.settings.field_name_limit
             and len(node.astext()) > self.settings.field_name_limit):
            atts['colspan'] = 2
            self.context.append('\n ')
        else:
            self.context.append('')
        self.body.append(self.starttag(node, 'th', '', **atts))

    def depart_field_name(self, node):
        self.body.append(':')
        self.body.append(self.context.pop())

    def visit_figure(self, node):
        atts = {'class': 'figure'}
        if node.get('width'):
            atts['style'] = 'width: %spx' % node['width']
        if node.get('align'):
            atts['align'] = node['align']
        self.body.append(self.starttag(node, 'div', **atts))

    def depart_figure(self, node):
        self.body.append('
\n')

    def visit_footer(self, node):
        self.context.append(len(self.body))

    def depart_footer(self, node):
        start = self.context.pop()
        footer = [self.starttag(node, 'div', CLASS='footer'),
                  '
\n']
        footer.extend(self.body[start:])
        footer.append('\n
\n')
        self.footer.extend(footer)
        self.body_suffix[:0] = footer
        del self.body[start:]

    def visit_footnote(self, node):
        self.body.append(self.starttag(node, 'table',
                                       CLASS='docutils footnote',
                                       frame="void", rules="none"))
        self.body.append('\n'
                         '\n'
                         '')
        self.footnote_backrefs(node)

    def footnote_backrefs(self, node):
        backlinks = []
        backrefs = node['backrefs']
        if self.settings.footnote_backlinks and backrefs:
            if len(backrefs) == 1:
                self.context.append('')
                self.context.append(
                    ''
                    % (backrefs[0], node['ids'][0]))
            else:
                i = 1
                for backref in backrefs:
                    backlinks.append('%s'
                                     % (backref, i))
                    i += 1
                self.context.append('(%s) ' % ', '.join(backlinks))
                self.context.append('' % node['ids'][0])
        else:
            self.context.append('')
            self.context.append('' % node['ids'][0])
        # If the node does not only consist of a label.
        if len(node) > 1:
            # If there are preceding backlinks, we do not set class
            # 'first', because we need to retain the top-margin.
            if not backlinks:
                node[1]['classes'].append('first')
            node[-1]['classes'].append('last')

    def depart_footnote(self, node):
        self.body.append('\n'
                         '\n\n')

    def visit_footnote_reference(self, node):
        href = '#' + node['refid']
        format = self.settings.footnote_references
        if format == 'brackets':
            suffix = '['
            self.context.append(']')
        else:
            assert format == 'superscript'
            suffix = ''
            self.context.append('')
        self.body.append(self.starttag(node, 'a', suffix,
                                       CLASS='footnote-reference', href=href))

    def depart_footnote_reference(self, node):
        self.body.append(self.context.pop() + '')

    def visit_generated(self, node):
        pass

    def depart_generated(self, node):
        pass

    def visit_header(self, node):
        self.context.append(len(self.body))

    def depart_header(self, node):
        start = self.context.pop()
        header = [self.starttag(node, 'div', CLASS='header')]
        header.extend(self.body[start:])
        header.append('\n
\n
\n')
        self.body_prefix.extend(header)
        self.header.extend(header)
        del self.body[start:]

    def visit_hint(self, node):
        self.visit_admonition(node, 'hint')

    def depart_hint(self, node):
        self.depart_admonition()

    def visit_image(self, node):
        atts = node.non_default_attributes()
        if atts.has_key('classes'):
            del atts['classes']         # prevent duplication with node attrs
        atts['src'] = atts['uri']
        del atts['uri']
        if atts.has_key('scale'):
            if Image and not (atts.has_key('width')
                              and atts.has_key('height')):
                try:
                    im = Image.open(str(atts['src']))
                except (IOError, # Source image can't be found or opened
                        UnicodeError):  # PIL doesn't like Unicode paths.
                    pass
                else:
                    if not atts.has_key('width'):
                        atts['width'] = im.size[0]
                    if not atts.has_key('height'):
                        atts['height'] = im.size[1]
                    del im
            if atts.has_key('width'):
                atts['width'] = int(round(atts['width']
                                          * (float(atts['scale']) / 100)))
            if atts.has_key('height'):
                atts['height'] = int(round(atts['height']
                                           * (float(atts['scale']) / 100)))
            del atts['scale']
        if not atts.has_key('alt'):
            atts['alt'] = atts['src']
        if isinstance(node.parent, nodes.TextElement):
            self.context.append('')
        else:
            div_atts = self.image_div_atts(node)
            self.body.append(self.starttag({}, 'div', '', **div_atts))
            self.context.append('\n')
        self.body.append(self.emptytag(node, 'img', '', **atts))

    def image_div_atts(self, image_node):
        div_atts = {}
        div_atts['class'] = ' '.join(['image'] + image_node['classes'])
        if image_node.attributes.has_key('align'):
            div_atts['align'] = self.attval(image_node.attributes['align'])
            div_atts['class'] += ' align-%s' % div_atts['align']
        return div_atts

    def depart_image(self, node):
        self.body.append(self.context.pop())

    def visit_important(self, node):
        self.visit_admonition(node, 'important')

    def depart_important(self, node):
        self.depart_admonition()

    def visit_inline(self, node):
        self.body.append(self.starttag(node, 'span', ''))

    def depart_inline(self, node):
        self.body.append('')

    def visit_label(self, node):
        self.body.append(self.starttag(node, 'td', '%s[' % self.context.pop(),
                                       CLASS='label'))

    def depart_label(self, node):
        self.body.append(']%s' % self.context.pop())

    def visit_legend(self, node):
        self.body.append(self.starttag(node, 'div', CLASS='legend'))

    def depart_legend(self, node):
        self.body.append('\n')

    def visit_line(self, node):
        self.body.append(self.starttag(node, 'div', suffix='', CLASS='line'))
        if not len(node):
            self.body.append('
')

    def depart_line(self, node):
        self.body.append('\n')

    def visit_line_block(self, node):
        self.body.append(self.starttag(node, 'div', CLASS='line-block'))

    def depart_line_block(self, node):
        self.body.append('\n')

    def visit_list_item(self, node):
        self.body.append(self.starttag(node, 'li', ''))
        if len(node):
            node[0]['classes'].append('first')

    def depart_list_item(self, node):
        self.body.append('\n')

    def visit_literal(self, node):
        """Process text to prevent tokens from wrapping."""
        self.body.append(
            self.starttag(node, 'tt', '', CLASS='docutils literal'))
        text = node.astext()
        for token in self.words_and_spaces.findall(text):
            if token.strip():
                # Protect text like "--an-option" from bad line wrapping:
                self.body.append('%s'
                                 % self.encode(token))
            elif token in ('\n', ' '):
                # Allow breaks at whitespace:
                self.body.append(token)
            else:
                # Protect runs of multiple spaces; the last space can wrap:
                self.body.append(' ' * (len(token) - 1) + ' ')
        self.body.append('')
        # Content already processed:
        raise nodes.SkipNode

    def visit_literal_block(self, node):
        self.body.append(self.starttag(node, 'pre', CLASS='literal-block'))

    def depart_literal_block(self, node):
        self.body.append('\n\n')

    def visit_meta(self, node):
        meta = self.emptytag(node, 'meta', **node.non_default_attributes())
        self.add_meta(meta)

    def depart_meta(self, node):
        pass

    def add_meta(self, tag):
        self.meta.append(tag)
        self.head.append(tag)

    def visit_note(self, node):
        self.visit_admonition(node, 'note')

    def depart_note(self, node):
        self.depart_admonition()

    def visit_option(self, node):
        if self.context[-1]:
            self.body.append(', ')
        self.body.append(self.starttag(node, 'span', '', CLASS='option'))

    def depart_option(self, node):
        self.body.append('')
        self.context[-1] += 1

    def visit_option_argument(self, node):
        self.body.append(node.get('delimiter', ' '))
        self.body.append(self.starttag(node, 'var', ''))

    def depart_option_argument(self, node):
        self.body.append('')

    def visit_option_group(self, node):
        atts = {}
        if ( self.settings.option_limit
             and len(node.astext()) > self.settings.option_limit):
            atts['colspan'] = 2
            self.context.append('\n ')
        else:
            self.context.append('')
        self.body.append(
            self.starttag(node, 'td', CLASS='option-group', **atts))
        self.body.append('')
        self.context.append(0)          # count number of options

    def depart_option_group(self, node):
        self.context.pop()
        self.body.append('\n')
        self.body.append(self.context.pop())

    def visit_option_list(self, node):
        self.body.append(
              self.starttag(node, 'table', CLASS='docutils option-list',
                            frame="void", rules="none"))
        self.body.append('\n'
                         '\n'
                         '\n')

    def depart_option_list(self, node):
        self.body.append('\n\n')

    def visit_option_list_item(self, node):
        self.body.append(self.starttag(node, 'tr', ''))

    def depart_option_list_item(self, node):
        self.body.append('\n')

    def visit_option_string(self, node):
        pass

    def depart_option_string(self, node):
        pass

    def visit_organization(self, node):
        self.visit_docinfo_item(node, 'organization')

    def depart_organization(self, node):
        self.depart_docinfo_item()

    def should_be_compact_paragraph(self, node):
        """
        Determine if the 
 tags around paragraph ``node`` can be omitted.
        """
        if (isinstance(node.parent, nodes.document) or
            isinstance(node.parent, nodes.compound)):
            # Never compact paragraphs in document or compound.
            return 0
        for key, value in node.attlist():
            if (node.is_not_default(key) and
                not (key == 'classes' and value in
                     ([], ['first'], ['last'], ['first', 'last']))):
                # Attribute which needs to survive.
                return 0
        if (self.compact_simple or
            self.compact_p and (len(node.parent) == 1 or
                                len(node.parent) == 2 and
                                isinstance(node.parent[0], nodes.label))):
            return 1
        return 0

    def visit_paragraph(self, node):
        if self.should_be_compact_paragraph(node):
            self.context.append('')
        else:
            self.body.append(self.starttag(node, 'p', ''))
            self.context.append('
\n')

    def depart_paragraph(self, node):
        self.body.append(self.context.pop())

    def visit_problematic(self, node):
        if node.hasattr('refid'):
            self.body.append('' % (node['refid'],
                                                           node['ids'][0]))
            self.context.append('')
        else:
            self.context.append('')
        self.body.append(self.starttag(node, 'span', '', CLASS='problematic'))

    def depart_problematic(self, node):
        self.body.append('')
        self.body.append(self.context.pop())

    def visit_raw(self, node):
        if 'html' in node.get('format', '').split():
            t = isinstance(node.parent, nodes.TextElement) and 'span' or 'div'
            if node['classes']:
                self.body.append(self.starttag(node, t, suffix=''))
            self.body.append(node.astext())
            if node['classes']:
                self.body.append('' % t)
        # Keep non-HTML raw text out of output:
        raise nodes.SkipNode

    def visit_reference(self, node):
        if isinstance(node.parent, nodes.TextElement):
            self.context.append('')
        else:                           # contains an image
            assert len(node) == 1 and isinstance(node[0], nodes.image)
            div_atts = self.image_div_atts(node[0])
            div_atts['class'] += ' image-reference'
            self.body.append(self.starttag({}, 'div', '', **div_atts))
            self.context.append('\n')
        if node.has_key('refuri'):
            href = node['refuri']
            if ( self.settings.cloak_email_addresses
                 and href.startswith('mailto:')):
                href = self.cloak_mailto(href)
                self.in_mailto = 1
        else:
            assert node.has_key('refid'), \
                   'References must have "refuri" or "refid" attribute.'
            href = '#' + node['refid']
        self.body.append(self.starttag(node, 'a', '', CLASS='reference',
                                       href=href))

    def depart_reference(self, node):
        self.body.append('')
        self.body.append(self.context.pop())
        self.in_mailto = 0

    def visit_revision(self, node):
        self.visit_docinfo_item(node, 'revision', meta=None)

    def depart_revision(self, node):
        self.depart_docinfo_item()

    def visit_row(self, node):
        self.body.append(self.starttag(node, 'tr', ''))
        node.column = 0

    def depart_row(self, node):
        self.body.append('\n')

    def visit_rubric(self, node):
        self.body.append(self.starttag(node, 'p', '', CLASS='rubric'))

    def depart_rubric(self, node):
        self.body.append('
\n')

    def visit_section(self, node):
        self.section_level += 1
        self.body.append(self.starttag(node, 'div', CLASS='section'))

    def depart_section(self, node):
        self.section_level -= 1
        self.body.append('\n')

    def visit_sidebar(self, node):
        self.body.append(self.starttag(node, 'div', CLASS='sidebar'))
        self.set_first_last(node)
        self.in_sidebar = 1

    def depart_sidebar(self, node):
        self.body.append('\n')
        self.in_sidebar = None

    def visit_status(self, node):
        self.visit_docinfo_item(node, 'status', meta=None)

    def depart_status(self, node):
        self.depart_docinfo_item()

    def visit_strong(self, node):
        self.body.append('')

    def depart_strong(self, node):
        self.body.append('')

    def visit_subscript(self, node):
        self.body.append(self.starttag(node, 'sub', ''))

    def depart_subscript(self, node):
        self.body.append('')

    def visit_substitution_definition(self, node):
        """Internal only."""
        raise nodes.SkipNode

    def visit_substitution_reference(self, node):
        self.unimplemented_visit(node)

    def visit_subtitle(self, node):
        if isinstance(node.parent, nodes.sidebar):
            self.body.append(self.starttag(node, 'p', '',
                                           CLASS='sidebar-subtitle'))
            self.context.append('
\n')
        elif isinstance(node.parent, nodes.document):
            self.body.append(self.starttag(node, 'h2', '', CLASS='subtitle'))
            self.context.append('\n')
            self.in_document_title = len(self.body)
        elif isinstance(node.parent, nodes.section):
            tag = 'h%s' % (self.section_level + self.initial_header_level - 1)
            self.body.append(
                self.starttag(node, tag, '', CLASS='section-subtitle') +
                self.starttag({}, 'span', '', CLASS='section-subtitle'))
            self.context.append('\n' % tag)

    def depart_subtitle(self, node):
        self.body.append(self.context.pop())
        if self.in_document_title:
            self.subtitle = self.body[self.in_document_title:-1]
            self.in_document_title = 0
            self.body_pre_docinfo.extend(self.body)
            self.html_subtitle.extend(self.body)
            del self.body[:]

    def visit_superscript(self, node):
        self.body.append(self.starttag(node, 'sup', ''))

    def depart_superscript(self, node):
        self.body.append('')

    def visit_system_message(self, node):
        if node['level'] < self.document.reporter.report_level:
            # Level is too low to display:
            raise nodes.SkipNode
        self.body.append(self.starttag(node, 'div', CLASS='system-message'))
        self.body.append('
')
        attr = {}
        backref_text = ''
        if node['ids']:
            attr['name'] = node['ids'][0]
        if len(node['backrefs']):
            backrefs = node['backrefs']
            if len(backrefs) == 1:
                backref_text = ('; backlink'
                                % backrefs[0])
            else:
                i = 1
                backlinks = []
                for backref in backrefs:
                    backlinks.append('%s' % (backref, i))
                    i += 1
                backref_text = ('; backlinks: %s'
                                % ', '.join(backlinks))
        if node.hasattr('line'):
            line = ', line %s' % node['line']
        else:
            line = ''
        if attr:
            a_start = self.starttag({}, 'a', '', **attr)
            a_end = ''
        else:
            a_start = a_end = ''
        self.body.append('System Message: %s%s/%s%s '
                         '(%s%s)%s
\n'
                         % (a_start, node['type'], node['level'], a_end,
                            self.encode(node['source']), line, backref_text))

    def depart_system_message(self, node):
        self.body.append('\n')

    def visit_table(self, node):
        self.body.append(
            self.starttag(node, 'table', CLASS='docutils', border="1"))

    def depart_table(self, node):
        self.body.append('\n')

    def visit_target(self, node):
        if not (node.has_key('refuri') or node.has_key('refid')
                or node.has_key('refname')):
            self.body.append(self.starttag(node, 'span', '', CLASS='target'))
            self.context.append('')
        else:
            self.context.append('')

    def depart_target(self, node):
        self.body.append(self.context.pop())

    def visit_tbody(self, node):
        self.write_colspecs()
        self.body.append(self.context.pop()) # '\n' or ''
        self.body.append(self.starttag(node, 'tbody', valign='top'))

    def depart_tbody(self, node):
        self.body.append('\n')

    def visit_term(self, node):
        self.body.append(self.starttag(node, 'dt', ''))

    def depart_term(self, node):
        """
        Leave the end tag to `self.visit_definition()`, in case there's a
        classifier.
        """
        pass

    def visit_tgroup(self, node):
        # Mozilla needs :
        self.body.append(self.starttag(node, 'colgroup'))
        # Appended by thead or tbody:
        self.context.append('\n')
        node.stubs = []

    def depart_tgroup(self, node):
        pass

    def visit_thead(self, node):
        self.write_colspecs()
        self.body.append(self.context.pop()) # '\n'
        # There may or may not be a ; this is for  to use:
        self.context.append('')
        self.body.append(self.starttag(node, 'thead', valign='bottom'))

    def depart_thead(self, node):
        self.body.append('\n')

    def visit_tip(self, node):
        self.visit_admonition(node, 'tip')

    def depart_tip(self, node):
        self.depart_admonition()

    def visit_title(self, node):
        """Only 6 section levels are supported by HTML."""
        check_id = 0
        close_tag = '
\n'
        if isinstance(node.parent, nodes.topic):
            self.body.append(
                  self.starttag(node, 'p', '', CLASS='topic-title first'))
            check_id = 1
        elif isinstance(node.parent, nodes.sidebar):
            self.body.append(
                  self.starttag(node, 'p', '', CLASS='sidebar-title'))
            check_id = 1
        elif isinstance(node.parent, nodes.Admonition):
            self.body.append(
                  self.starttag(node, 'p', '', CLASS='admonition-title'))
            check_id = 1
        elif isinstance(node.parent, nodes.table):
            self.body.append(
                  self.starttag(node, 'caption', ''))
            check_id = 1
            close_tag = '\n'
        elif self.section_level == 0:
            assert node.parent is self.document
            # document title
            self.head.append('%s\n'
                             % self.encode(node.astext()))
            self.body.append(self.starttag(node, 'h1', '', CLASS='title'))
            self.context.append('\n')
            self.in_document_title = len(self.body)
        else:
            assert isinstance(node.parent, nodes.section)
            h_level = self.section_level + self.initial_header_level - 1
            atts = {}
            if (len(node.parent) >= 2 and
                isinstance(node.parent[1], nodes.subtitle)):
                atts['CLASS'] = 'with-subtitle'
            self.body.append(
                  self.starttag(node, 'h%s' % h_level, '', **atts))
            atts = {}
            if node.parent['ids']:
                atts['name'] = node.parent['ids'][0]
            if node.hasattr('refid'):
                atts['class'] = 'toc-backref'
                atts['href'] = '#' + node['refid']
            self.body.append(self.starttag({}, 'a', '', **atts))
            self.context.append('\n' % (h_level))
        if check_id:
            if node.parent['ids']:
                self.body.append(
                    self.starttag({}, 'a', '', name=node.parent['ids'][0]))
                self.context.append('' + close_tag)
            else:
                self.context.append(close_tag)

    def depart_title(self, node):
        self.body.append(self.context.pop())
        if self.in_document_title:
            self.title = self.body[self.in_document_title:-1]
            self.in_document_title = 0
            self.body_pre_docinfo.extend(self.body)
            self.html_title.extend(self.body)
            del self.body[:]

    def visit_title_reference(self, node):
        self.body.append(self.starttag(node, 'cite', ''))

    def depart_title_reference(self, node):
        self.body.append('')

    def visit_topic(self, node):
        self.body.append(self.starttag(node, 'div', CLASS='topic'))
        self.topic_classes = node['classes']

    def depart_topic(self, node):
        self.body.append('\n')
        self.topic_classes = []

    def visit_transition(self, node):
        self.body.append(self.emptytag(node, 'hr', CLASS='docutils'))

    def depart_transition(self, node):
        pass

    def visit_version(self, node):
        self.visit_docinfo_item(node, 'version', meta=None)

    def depart_version(self, node):
        self.depart_docinfo_item()

    def visit_warning(self, node):
        self.visit_admonition(node, 'warning')

    def depart_warning(self, node):
        self.depart_admonition()

    def unimplemented_visit(self, node):
        raise NotImplementedError('visiting unimplemented node type: %s'
                                  % node.__class__.__name__)


class SimpleListChecker(nodes.GenericNodeVisitor):

    """
    Raise `nodes.NodeFound` if non-simple list item is encountered.

    Here "simple" means a list item containing nothing other than a single
    paragraph, a simple list, or a paragraph followed by a simple list.
    """

    def default_visit(self, node):
        raise nodes.NodeFound

    def visit_bullet_list(self, node):
        pass

    def visit_enumerated_list(self, node):
        pass

    def visit_list_item(self, node):
        children = []
        for child in node.children:
            if not isinstance(child, nodes.Invisible):
                children.append(child)
        if (children and isinstance(children[0], nodes.paragraph)
            and (isinstance(children[-1], nodes.bullet_list)
                 or isinstance(children[-1], nodes.enumerated_list))):
            children.pop()
        if len(children) <= 1:
            return
        else:
            raise nodes.NodeFound

    def visit_paragraph(self, node):
        raise nodes.SkipNode

    def invisible_visit(self, node):
        """Invisible nodes should be ignored."""
        raise nodes.SkipNode

    visit_comment = invisible_visit
    visit_substitution_definition = invisible_visit
    visit_target = invisible_visit
    visit_pending = invisible_visit
Zope-2.9.4-retire_zpkg/lib/python/docutils/writers/latex2e.py0000644000175000017500000022442510322224711024227 0ustar  tseavertseaver"""
:Author: Engelbert Gruber
:Contact: grubert@users.sourceforge.net
:Revision: $Revision: 3367 $
:Date: $Date: 2005-05-26 02:44:13 +0200 (Thu, 26 May 2005) $
:Copyright: This module has been placed in the public domain.

LaTeX2e document tree Writer.
"""

__docformat__ = 'reStructuredText'

# code contributions from several people included, thanks to all.
# some named: David Abrahams, Julien Letessier, Lele Gaifax, and others.
#
# convention deactivate code by two # e.g. ##.

import sys
import time
import re
import string
from types import ListType
from docutils import frontend, nodes, languages, writers, utils

class Writer(writers.Writer):

    supported = ('latex','latex2e')
    """Formats this writer supports."""

    settings_spec = (
        'LaTeX-Specific Options',
        'The LaTeX "--output-encoding" default is "latin-1:strict".',
        (('Specify documentclass.  Default is "article".',
          ['--documentclass'],
          {'default': 'article', }),
         ('Specify document options.  Multiple options can be given, '
          'separated by commas.  Default is "10pt,a4paper".',
          ['--documentoptions'],
          {'default': '10pt,a4paper', }),
         ('Use LaTeX footnotes. LaTeX supports only numbered footnotes (does it?). '
          'Default: no, uses figures.',
          ['--use-latex-footnotes'],
          {'default': 0, 'action': 'store_true',
           'validator': frontend.validate_boolean}),
         ('Format for footnote references: one of "superscript" or '
          '"brackets".  Default is "superscript".',
          ['--footnote-references'],
          {'choices': ['superscript', 'brackets'], 'default': 'superscript',
           'metavar': '',
           'overrides': 'trim_footnote_reference_space'}),
         ('Use LaTeX citations. '
          'Default: no, uses figures which might get mixed with images.',
          ['--use-latex-citations'],
          {'default': 0, 'action': 'store_true',
           'validator': frontend.validate_boolean}),
         ('Format for block quote attributions: one of "dash" (em-dash '
          'prefix), "parentheses"/"parens", or "none".  Default is "dash".',
          ['--attribution'],
          {'choices': ['dash', 'parentheses', 'parens', 'none'],
           'default': 'dash', 'metavar': ''}),
         ('Specify a stylesheet file. The file will be "input" by latex in '
          'the document header.  Default is no stylesheet ("").  '
          'Overrides --stylesheet-path.',
          ['--stylesheet'],
          {'default': '', 'metavar': '',
           'overrides': 'stylesheet_path'}),
         ('Specify a stylesheet file, relative to the current working '
          'directory.  Overrides --stylesheet.',
          ['--stylesheet-path'],
          {'metavar': '', 'overrides': 'stylesheet'}),
         ('Table of contents by docutils (default) or latex. Latex (writer) '
          'supports only one ToC per document, but docutils does not write '
          'pagenumbers.',
          ['--use-latex-toc'],
          {'default': 0, 'action': 'store_true',
           'validator': frontend.validate_boolean}),
         ('Let LaTeX print author and date, do not show it in docutils '
          'document info.',
          ['--use-latex-docinfo'],
          {'default': 0, 'action': 'store_true',
           'validator': frontend.validate_boolean}),
         ('Color of any hyperlinks embedded in text '
          '(default: "blue", "0" to disable).',
          ['--hyperlink-color'], {'default': 'blue'}),
         ('Enable compound enumerators for nested enumerated lists '
          '(e.g. "1.2.a.ii").  Default: disabled.',
          ['--compound-enumerators'],
          {'default': None, 'action': 'store_true',
           'validator': frontend.validate_boolean}),
         ('Disable compound enumerators for nested enumerated lists.  This is '
          'the default.',
          ['--no-compound-enumerators'],
          {'action': 'store_false', 'dest': 'compound_enumerators'}),
         ('Enable section ("." subsection ...) prefixes for compound '
          'enumerators.  This has no effect without --compound-enumerators.  '
          'Default: disabled.',
          ['--section-prefix-for-enumerators'],
          {'default': None, 'action': 'store_true',
           'validator': frontend.validate_boolean}),
         ('Disable section prefixes for compound enumerators.  '
          'This is the default.',
          ['--no-section-prefix-for-enumerators'],
          {'action': 'store_false', 'dest': 'section_prefix_for_enumerators'}),
         ('Set the separator between section number and enumerator '
          'for compound enumerated lists.  Default is "-".',
          ['--section-enumerator-separator'],
          {'default': '-', 'metavar': ''}),
         ('When possibile, use verbatim for literal-blocks. '
          'Default is to always use the mbox environment.',
          ['--use-verbatim-when-possible'],
          {'default': 0, 'action': 'store_true',
           'validator': frontend.validate_boolean}),
         ('Table style. "standard" with horizontal and vertical lines, '
          '"booktabs" (LaTeX booktabs style) only horizontal lines '
          'above and below the table and below the header or "nolines".  '
          'Default: "standard"',
          ['--table-style'],
          {'choices': ['standard', 'booktabs','nolines'], 'default': 'standard',
           'metavar': ''}),
         ('LaTeX graphicx package option. '
          'Possible values are "dvips", "pdftex". "auto" includes LaTeX code '
          'to use "pdftex" if processing with pdf(la)tex and dvips otherwise. '
          'Default is no option.',
          ['--graphicx-option'],
          {'default': ''}),
         ('LaTeX font encoding. '
          'Possible values are "T1", "OT1", "" or some other fontenc option. '
          'The font encoding influences available symbols, e.g. "<<" as one '
          'character. Default is "" which leads to package "ae" (a T1 '
          'emulation using CM fonts).',
          ['--font-encoding'],
          {'default': ''}),
          ),)

    settings_defaults = {'output_encoding': 'latin-1'}

    relative_path_settings = ('stylesheet_path',)

    config_section = 'latex2e writer'
    config_section_dependencies = ('writers',)

    output = None
    """Final translated form of `document`."""

    def __init__(self):
        writers.Writer.__init__(self)
        self.translator_class = LaTeXTranslator

    def translate(self):
        visitor = self.translator_class(self.document)
        self.document.walkabout(visitor)
        self.output = visitor.astext()
        self.head_prefix = visitor.head_prefix
        self.head = visitor.head
        self.body_prefix = visitor.body_prefix
        self.body = visitor.body
        self.body_suffix = visitor.body_suffix

"""
Notes on LaTeX
--------------

* latex does not support multiple tocs in one document.
  (might be no limitation except for docutils documentation)

* width

  * linewidth - width of a line in the local environment
  * textwidth - the width of text on the page

  Maybe always use linewidth ?

  *Bug* inside a minipage a (e.g. Sidebar) the linewidth is
        not changed, needs fix in docutils so that tables
        are not too wide.

        So we add locallinewidth set it initially and
        on entering sidebar and reset on exit.
"""

class Babel:
    """Language specifics for LaTeX."""
    # country code by a.schlock.
    # partly manually converted from iso and babel stuff, dialects and some
    _ISO639_TO_BABEL = {
        'no': 'norsk',     #XXX added by hand ( forget about nynorsk?)
        'gd': 'scottish',  #XXX added by hand
        'hu': 'magyar',    #XXX added by hand
        'pt': 'portuguese',#XXX added by hand
        'sl': 'slovenian',
        'af': 'afrikaans',
        'bg': 'bulgarian',
        'br': 'breton',
        'ca': 'catalan',
        'cs': 'czech',
        'cy': 'welsh',
        'da': 'danish',
        'fr': 'french',
        # french, francais, canadien, acadian
        'de': 'ngerman',  #XXX rather than german
        # ngerman, naustrian, german, germanb, austrian
        'el': 'greek',
        'en': 'english',
        # english, USenglish, american, UKenglish, british, canadian
        'eo': 'esperanto',
        'es': 'spanish',
        'et': 'estonian',
        'eu': 'basque',
        'fi': 'finnish',
        'ga': 'irish',
        'gl': 'galician',
        'he': 'hebrew',
        'hr': 'croatian',
        'hu': 'hungarian',
        'is': 'icelandic',
        'it': 'italian',
        'la': 'latin',
        'nl': 'dutch',
        'pl': 'polish',
        'pt': 'portuguese',
        'ro': 'romanian',
        'ru': 'russian',
        'sk': 'slovak',
        'sr': 'serbian',
        'sv': 'swedish',
        'tr': 'turkish',
        'uk': 'ukrainian'
    }

    def __init__(self,lang):
        self.language = lang
        # pdflatex does not produce double quotes for ngerman in tt.
        self.double_quote_replacment = None
        if re.search('^de',self.language):
            #self.quotes = ("\"`", "\"'")
            self.quotes = ('{\\glqq}', '{\\grqq}')
            self.double_quote_replacment = "{\\dq}"
        else:
            self.quotes = ("``", "''")
        self.quote_index = 0

    def next_quote(self):
        q = self.quotes[self.quote_index]
        self.quote_index = (self.quote_index+1)%2
        return q

    def quote_quotes(self,text):
        t = None
        for part in text.split('"'):
            if t == None:
                t = part
            else:
                t += self.next_quote() + part
        return t

    def double_quotes_in_tt (self,text):
        if not self.double_quote_replacment:
            return text
        return text.replace('"', self.double_quote_replacment)

    def get_language(self):
        if self._ISO639_TO_BABEL.has_key(self.language):
            return self._ISO639_TO_BABEL[self.language]
        else:
            # support dialects.
            l = self.language.split("_")[0]
            if self._ISO639_TO_BABEL.has_key(l):
                return self._ISO639_TO_BABEL[l]
        return None


latex_headings = {
        'optionlist_environment' : [
              '\\newcommand{\\optionlistlabel}[1]{\\bf #1 \\hfill}\n'
              '\\newenvironment{optionlist}[1]\n'
              '{\\begin{list}{}\n'
              '  {\\setlength{\\labelwidth}{#1}\n'
              '   \\setlength{\\rightmargin}{1cm}\n'
              '   \\setlength{\\leftmargin}{\\rightmargin}\n'
              '   \\addtolength{\\leftmargin}{\\labelwidth}\n'
              '   \\addtolength{\\leftmargin}{\\labelsep}\n'
              '   \\renewcommand{\\makelabel}{\\optionlistlabel}}\n'
              '}{\\end{list}}\n',
              ],
        'lineblock_environment' : [
            '\\newlength{\\lineblockindentation}\n'
            '\\setlength{\\lineblockindentation}{2.5em}\n'
            '\\newenvironment{lineblock}[1]\n'
            '{\\begin{list}{}\n'
            '  {\\setlength{\\partopsep}{\\parskip}\n'
            '   \\addtolength{\\partopsep}{\\baselineskip}\n'
            '   \\topsep0pt\\itemsep0.15\\baselineskip\\parsep0pt\n'
            '   \\leftmargin#1}\n'
            ' \\raggedright}\n'
            '{\\end{list}}\n'
            ],
        'footnote_floats' : [
            '% begin: floats for footnotes tweaking.\n',
            '\\setlength{\\floatsep}{0.5em}\n',
            '\\setlength{\\textfloatsep}{\\fill}\n',
            '\\addtolength{\\textfloatsep}{3em}\n',
            '\\renewcommand{\\textfraction}{0.5}\n',
            '\\renewcommand{\\topfraction}{0.5}\n',
            '\\renewcommand{\\bottomfraction}{0.5}\n',
            '\\setcounter{totalnumber}{50}\n',
            '\\setcounter{topnumber}{50}\n',
            '\\setcounter{bottomnumber}{50}\n',
            '% end floats for footnotes\n',
            ],
        'some_commands' : [
            '% some commands, that could be overwritten in the style file.\n'
            '\\newcommand{\\rubric}[1]'
            '{\\subsection*{~\\hfill {\\it #1} \\hfill ~}}\n'
            '\\newcommand{\\titlereference}[1]{\\textsl{#1}}\n'
            '% end of "some commands"\n',
            ]
        }

class DocumentClass:
    """Details of a LaTeX document class."""

    # BUG: LaTeX has no deeper sections (actually paragrah is no
    # section either).
    # BUG: No support for unknown document classes.  Make 'article'
    # default?
    _class_sections = {
        'book': ( 'chapter', 'section', 'subsection', 'subsubsection' ),
        'scrbook': ( 'chapter', 'section', 'subsection', 'subsubsection' ),
        'report': ( 'chapter', 'section', 'subsection', 'subsubsection' ),
        'scrreprt': ( 'chapter', 'section', 'subsection', 'subsubsection' ),
        'article': ( 'section', 'subsection', 'subsubsection' ),
        'scrartcl': ( 'section', 'subsection', 'subsubsection' ),
        }
    _deepest_section = 'subsubsection'

    def __init__(self, document_class):
        self.document_class = document_class

    def section(self, level):
        """ Return the section name at the given level for the specific
            document class.

            Level is 1,2,3..., as level 0 is the title."""

        sections = self._class_sections[self.document_class]
        if level <= len(sections):
            return sections[level-1]
        else:
            return self._deepest_section

class Table:
    """ Manage a table while traversing.
        Maybe change to a mixin defining the visit/departs, but then
        class Table internal variables are in the Translator.
    """
    def __init__(self,latex_type,table_style):
        self._latex_type = latex_type
        self._table_style = table_style
        self._open = 0
        # miscellaneous attributes
        self._attrs = {}
        self._col_width = []
        self._rowspan = []

    def open(self):
        self._open = 1
        self._col_specs = []
        self.caption = None
        self._attrs = {}
        self._in_head = 0 # maybe context with search
    def close(self):
        self._open = 0
        self._col_specs = None
        self.caption = None
        self._attrs = {}
    def is_open(self):
        return self._open
    def used_packages(self):
        if self._table_style == 'booktabs':
            return '\\usepackage{booktabs}\n'
        return ''
    def get_latex_type(self):
        return self._latex_type

    def set(self,attr,value):
        self._attrs[attr] = value
    def get(self,attr):
        if self._attrs.has_key(attr):
            return self._attrs[attr]
        return None
    def get_vertical_bar(self):
        if self._table_style == 'standard':
            return '|'
        return ''
    # horizontal lines are drawn below a row, because we.
    def get_opening(self):
        return '\\begin{%s}[c]' % self._latex_type
    def get_closing(self):
        line = ""
        if self._table_style == 'booktabs':
            line = '\\bottomrule\n'
        elif self._table_style == 'standard':
            lines = '\\hline\n'
        return '%s\\end{%s}' % (line,self._latex_type)

    def visit_colspec(self,node):
        self._col_specs.append(node)

    def get_colspecs(self):
        """
        Return column specification for longtable.

        Assumes reST line length being 80 characters.
        Table width is hairy.

        === ===
        ABC DEF
        === ===

        usually gets to narrow, therefore we add 1 (fiddlefactor).
        """
        width = 80

        total_width = 0.0
        # first see if we get too wide.
        for node in self._col_specs:
            colwidth = float(node['colwidth']+1) / width
            total_width += colwidth
        self._col_width = []
        self._rowspan = []
        # donot make it full linewidth
        factor = 0.93
        if total_width > 1.0:
            factor /= total_width
        bar = self.get_vertical_bar()
        latex_table_spec = ""
        for node in self._col_specs:
            colwidth = factor * float(node['colwidth']+1) / width
            self._col_width.append(colwidth+0.005)
            self._rowspan.append(0)
            latex_table_spec += "%sp{%.2f\\locallinewidth}" % (bar,colwidth+0.005)
        return latex_table_spec+bar

    def get_column_width(self):
        """ return columnwidth for current cell (not multicell)
        """
        return "%.2f\\locallinewidth" % self._col_width[self._cell_in_row-1]

    def visit_thead(self):
        self._in_thead = 1
        if self._table_style == 'standard':
            return ['\\hline\n']
        elif self._table_style == 'booktabs':
            return ['\\toprule\n']
        return []
    def depart_thead(self):
        a = []
        #if self._table_style == 'standard':
        #    a.append('\\hline\n')
        if self._table_style == 'booktabs':
            a.append('\\midrule\n')
        a.append('\\endhead\n')
        # for longtable one could add firsthead, foot and lastfoot
        self._in_thead = 0
        return a
    def visit_row(self):
        self._cell_in_row = 0
    def depart_row(self):
        res = [' \\\\\n']
        self._cell_in_row = None  # remove cell counter
        for i in range(len(self._rowspan)):
            if (self._rowspan[i]>0):
                self._rowspan[i] -= 1

        if self._table_style == 'standard':
            rowspans = []
            for i in range(len(self._rowspan)):
                if (self._rowspan[i]<=0):
                    rowspans.append(i+1)
            if len(rowspans)==len(self._rowspan):
                res.append('\\hline\n')
            else:
                cline = ''
                rowspans.reverse()
                # TODO merge clines
                while 1:
                    try:
                        c_start = rowspans.pop()
                    except:
                        break
                    cline += '\\cline{%d-%d}\n' % (c_start,c_start)
                res.append(cline)
        return res

    def set_rowspan(self,cell,value):
        try:
            self._rowspan[cell] = value
        except:
            pass
    def get_rowspan(self,cell):
        try:
            return self._rowspan[cell]
        except:
            return 0
    def get_entry_number(self):
        return self._cell_in_row
    def visit_entry(self):
        self._cell_in_row += 1


class LaTeXTranslator(nodes.NodeVisitor):

    # When options are given to the documentclass, latex will pass them
    # to other packages, as done with babel.
    # Dummy settings might be taken from document settings

    latex_head = '\\documentclass[%s]{%s}\n'
    encoding = '\\usepackage[%s]{inputenc}\n'
    linking = '\\usepackage[colorlinks=%s,linkcolor=%s,urlcolor=%s]{hyperref}\n'
    stylesheet = '\\input{%s}\n'
    # add a generated on day , machine by user using docutils version.
    generator = '%% generator Docutils: http://docutils.sourceforge.net/\n'

    # use latex tableofcontents or let docutils do it.
    use_latex_toc = 0

    # TODO: use mixins for different implementations.
    # list environment for option-list. else tabularx
    use_optionlist_for_option_list = 1
    # list environment for docinfo. else tabularx
    use_optionlist_for_docinfo = 0 # NOT YET IN USE

    # Use compound enumerations (1.A.1.)
    compound_enumerators = 0

    # If using compound enumerations, include section information.
    section_prefix_for_enumerators = 0

    # This is the character that separates the section ("." subsection ...)
    # prefix from the regular list enumerator.
    section_enumerator_separator = '-'

    # default link color
    hyperlink_color = "blue"

    def __init__(self, document):
        nodes.NodeVisitor.__init__(self, document)
        self.settings = settings = document.settings
        self.latex_encoding = self.to_latex_encoding(settings.output_encoding)
        self.use_latex_toc = settings.use_latex_toc
        self.use_latex_docinfo = settings.use_latex_docinfo
        self.use_latex_footnotes = settings.use_latex_footnotes
        self._use_latex_citations = settings.use_latex_citations
        self.hyperlink_color = settings.hyperlink_color
        self.compound_enumerators = settings.compound_enumerators
        self.font_encoding = settings.font_encoding
        self.section_prefix_for_enumerators = (
            settings.section_prefix_for_enumerators)
        self.section_enumerator_separator = (
            settings.section_enumerator_separator.replace('_', '\\_'))
        if self.hyperlink_color == '0':
            self.hyperlink_color = 'black'
            self.colorlinks = 'false'
        else:
            self.colorlinks = 'true'

        # language: labels, bibliographic_fields, and author_separators.
        # to allow writing labes for specific languages.
        self.language = languages.get_language(settings.language_code)
        self.babel = Babel(settings.language_code)
        self.author_separator = self.language.author_separators[0]
        self.d_options = self.settings.documentoptions
        if self.babel.get_language():
            self.d_options += ',%s' % \
                    self.babel.get_language()

        self.d_class = DocumentClass(settings.documentclass)
        # object for a table while proccessing.
        self.active_table = Table('longtable',settings.table_style)

        # HACK.  Should have more sophisticated typearea handling.
        if settings.documentclass.find('scr') == -1:
            self.typearea = '\\usepackage[DIV12]{typearea}\n'
        else:
            if self.d_options.find('DIV') == -1 and self.d_options.find('BCOR') == -1:
                self.typearea = '\\typearea{12}\n'
            else:
                self.typearea = ''

        if self.font_encoding == 'OT1':
            fontenc_header = ''
        elif self.font_encoding == '':
            fontenc_header = '\\usepackage{ae}\n\\usepackage{aeguill}\n'
        else:
            fontenc_header = '\\usepackage[%s]{fontenc}\n' % (self.font_encoding,)
        input_encoding = self.encoding % self.latex_encoding
        if self.settings.graphicx_option == '':
            self.graphicx_package = '\\usepackage{graphicx}\n'
        elif self.settings.graphicx_option.lower() == 'auto':
            self.graphicx_package = '\n'.join(
                ('%Check if we are compiling under latex or pdflatex',
                 '\\ifx\\pdftexversion\\undefined',
                 '  \\usepackage{graphicx}',
                 '\\else',
                 '  \\usepackage[pdftex]{graphicx}',
                 '\\fi\n'))
        else:
            self.graphicx_package = (
                '\\usepackage[%s]{graphicx}\n' % self.settings.graphicx_option)

        self.head_prefix = [
              self.latex_head % (self.d_options,self.settings.documentclass),
              '\\usepackage{babel}\n',     # language is in documents settings.
              fontenc_header,
              '\\usepackage{shortvrb}\n',  # allows verb in footnotes.
              input_encoding,
              # * tabularx: for docinfo, automatic width of columns, always on one page.
              '\\usepackage{tabularx}\n',
              '\\usepackage{longtable}\n',
              self.active_table.used_packages(),
              # possible other packages.
              # * fancyhdr
              # * ltxtable is a combination of tabularx and longtable (pagebreaks).
              #   but ??
              #
              # extra space between text in tables and the line above them
              '\\setlength{\\extrarowheight}{2pt}\n',
              '\\usepackage{amsmath}\n',   # what fore amsmath.
              self.graphicx_package,
              '\\usepackage{color}\n',
              '\\usepackage{multirow}\n',
              '\\usepackage{ifthen}\n',   # before hyperref!
              self.linking % (self.colorlinks, self.hyperlink_color, self.hyperlink_color),
              self.typearea,
              self.generator,
              # latex lengths
              '\\newlength{\\admonitionwidth}\n',
              '\\setlength{\\admonitionwidth}{0.9\\textwidth}\n'
              # width for docinfo tablewidth
              '\\newlength{\\docinfowidth}\n',
              '\\setlength{\\docinfowidth}{0.9\\textwidth}\n'
              # linewidth of current environment, so tables are not wider
              # than the sidebar: using locallinewidth seems to defer evaluation
              # of linewidth, this is fixing it.
              '\\newlength{\\locallinewidth}\n',
              # will be set later.
              ]
        self.head_prefix.extend( latex_headings['optionlist_environment'] )
        self.head_prefix.extend( latex_headings['lineblock_environment'] )
        self.head_prefix.extend( latex_headings['footnote_floats'] )
        self.head_prefix.extend( latex_headings['some_commands'] )
        ## stylesheet is last: so it might be possible to overwrite defaults.
        stylesheet = utils.get_stylesheet_reference(settings)
        if stylesheet:
            settings.record_dependencies.add(stylesheet)
            self.head_prefix.append(self.stylesheet % (stylesheet))

        if self.linking: # and maybe check for pdf
            self.pdfinfo = [ ]
            self.pdfauthor = None
            # pdftitle, pdfsubject, pdfauthor, pdfkeywords, pdfcreator, pdfproducer
        else:
            self.pdfinfo = None
        # NOTE: Latex wants a date and an author, rst puts this into
        #   docinfo, so normally we donot want latex author/date handling.
        # latex article has its own handling of date and author, deactivate.
        # So we always emit \title{...} \author{...} \date{...}, even if the
        # "..." are empty strings.
        self.head = [ ]
        # separate title, so we can appen subtitle.
        self.title = ''
        # if use_latex_docinfo: collects lists of author/organization/contact/address lines
        self.author_stack = []
        self.date = ''

        self.body_prefix = ['\\raggedbottom\n']
        self.body = []
        self.body_suffix = ['\n']
        self.section_level = 0
        self.context = []
        self.topic_classes = []
        # column specification for tables
        self.table_caption = None
        
        # Flags to encode
        # ---------------
        # verbatim: to tell encode not to encode.
        self.verbatim = 0
        # insert_newline: to tell encode to replace blanks by "~".
        self.insert_none_breaking_blanks = 0
        # insert_newline: to tell encode to add latex newline.
        self.insert_newline = 0
        # mbox_newline: to tell encode to add mbox and newline.
        self.mbox_newline = 0

        # enumeration is done by list environment.
        self._enum_cnt = 0

        # Stack of section counters so that we don't have to use_latex_toc.
        # This will grow and shrink as processing occurs.
        # Initialized for potential first-level sections.
        self._section_number = [0]

        # The current stack of enumerations so that we can expand
        # them into a compound enumeration
        self._enumeration_counters = []

        self._bibitems = []

        # docinfo.
        self.docinfo = None
        # inside literal block: no quote mangling.
        self.literal_block = 0
        self.literal_block_stack = []
        self.literal = 0
        # true when encoding in math mode
        self.mathmode = 0

    def to_latex_encoding(self,docutils_encoding):
        """
        Translate docutils encoding name into latex's.

        Default fallback method is remove "-" and "_" chars from docutils_encoding.

        """
        tr = {  "iso-8859-1": "latin1",     # west european
                "iso-8859-2": "latin2",     # east european
                "iso-8859-3": "latin3",     # esperanto, maltese
                "iso-8859-4": "latin4",     # north european,scandinavian, baltic
                "iso-8859-5": "iso88595",   # cyrillic (ISO)
                "iso-8859-9": "latin5",     # turkish
                "iso-8859-15": "latin9",    # latin9, update to latin1.
                "mac_cyrillic": "maccyr",   # cyrillic (on Mac)
                "windows-1251": "cp1251",   # cyrillic (on Windows)
                "koi8-r": "koi8-r",         # cyrillic (Russian)
                "koi8-u": "koi8-u",         # cyrillic (Ukrainian)
                "windows-1250": "cp1250",   #
                "windows-1252": "cp1252",   #
                "us-ascii": "ascii",        # ASCII (US)
                # unmatched encodings
                #"": "applemac",
                #"": "ansinew",  # windows 3.1 ansi
                #"": "ascii",    # ASCII encoding for the range 32--127.
                #"": "cp437",    # dos latine us
                #"": "cp850",    # dos latin 1
                #"": "cp852",    # dos latin 2
                #"": "decmulti",
                #"": "latin10",
                #"iso-8859-6": ""   # arabic
                #"iso-8859-7": ""   # greek
                #"iso-8859-8": ""   # hebrew
                #"iso-8859-10": ""   # latin6, more complete iso-8859-4
             }
        if tr.has_key(docutils_encoding.lower()):
            return tr[docutils_encoding.lower()]
        return docutils_encoding.translate(string.maketrans("",""),"_-").lower()

    def language_label(self, docutil_label):
        return self.language.labels[docutil_label]

    latex_equivalents = {
        u'\u00A0' : '~',
        u'\u2013' : '{--}',
        u'\u2014' : '{---}',
        u'\u2018' : '`',
        u'\u2019' : '\'',
        u'\u201A' : ',',
        u'\u201C' : '``',
        u'\u201D' : '\'\'',
        u'\u201E' : ',,',
        u'\u2020' : '{\\dag}',
        u'\u2021' : '{\\ddag}',
        u'\u2026' : '{\\dots}',
        u'\u2122' : '{\\texttrademark}',
        u'\u21d4' : '{$\\Leftrightarrow$}',
    }

    def unicode_to_latex(self,text):
        # see LaTeX codec
        # http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/252124
        # Only some special chracters are translated, for documents with many
        # utf-8 chars one should use the LaTeX unicode package.
        for uchar in self.latex_equivalents.keys():
            text = text.replace(uchar,self.latex_equivalents[uchar])
        return text

    def encode(self, text):
        """
        Encode special characters in `text` & return.
            # $ % & ~ _ ^ \ { }
        Escaping with a backslash does not help with backslashes, ~ and ^.

            < > are only available in math-mode or tt font. (really ?)
            $ starts math- mode.
        AND quotes:

        """
        if self.verbatim:
            return text
        # compile the regexps once. do it here so one can see them.
        #
        # first the braces.
        if not self.__dict__.has_key('encode_re_braces'):
            self.encode_re_braces = re.compile(r'([{}])')
        text = self.encode_re_braces.sub(r'{\\\1}',text)
        if not self.__dict__.has_key('encode_re_bslash'):
            # find backslash: except in the form '{\{}' or '{\}}'.
            self.encode_re_bslash = re.compile(r'(?", '{\\textgreater}')
        # then
        text = text.replace("&", '{\\&}')
        # the ^:
        # * verb|^| does not work in mbox.
        # * mathmode has wedge. hat{~} would also work.
        # text = text.replace("^", '{\\ensuremath{^\\wedge}}')
        text = text.replace("^", '{\\textasciicircum}')
        text = text.replace("%", '{\\%}')
        text = text.replace("#", '{\\#}')
        text = text.replace("~", '{\\textasciitilde}')
        # Separate compound characters, e.g. "--" to "-{}-".  (The
        # actual separation is done later; see below.)
        separate_chars = '-'
        if self.literal_block or self.literal:
            # In monospace-font, we also separate ",,", "``" and "''"
            # and some other characters which can't occur in
            # non-literal text.
            separate_chars += ',`\'"<>'
            # pdflatex does not produce doublequotes for ngerman.
            text = self.babel.double_quotes_in_tt(text)
            if self.font_encoding == 'OT1':
                # We're using OT1 font-encoding and have to replace
                # underscore by underlined blank, because this has
                # correct width.
                text = text.replace('_', '{\\underline{ }}')
                # And the tt-backslash doesn't work in OT1, so we use
                # a mirrored slash.
                text = text.replace('\\textbackslash', '\\reflectbox{/}')
            else:
                text = text.replace('_', '{\\_}')
        else:
            text = self.babel.quote_quotes(text)
            text = text.replace("_", '{\\_}')
        for char in separate_chars * 2:
            # Do it twice ("* 2") becaues otherwise we would replace
            # "---" by "-{}--".
            text = text.replace(char + char, char + '{}' + char)
        if self.insert_newline or self.literal_block:
            # Insert a blank before the newline, to avoid
            # ! LaTeX Error: There's no line here to end.
            text = text.replace("\n", '~\\\\\n')
        elif self.mbox_newline:
            if self.literal_block:
                closings = "}" * len(self.literal_block_stack)
                openings = "".join(self.literal_block_stack)
            else:
                closings = ""
                openings = ""
            text = text.replace("\n", "%s}\\\\\n\\mbox{%s" % (closings,openings))
        # lines starting with "[" give errors.
        text = text.replace('[', '{[}')
        if self.insert_none_breaking_blanks:
            text = text.replace(' ', '~')
        if self.latex_encoding != 'utf8':
            text = self.unicode_to_latex(text)
        return text

    def attval(self, text,
               whitespace=re.compile('[\n\r\t\v\f]')):
        """Cleanse, encode, and return attribute value text."""
        return self.encode(whitespace.sub(' ', text))

    def astext(self):
        if self.pdfinfo is not None:
            if self.pdfauthor:
                self.pdfinfo.append('pdfauthor={%s}' % self.pdfauthor)
        if self.pdfinfo:
            pdfinfo = '\\hypersetup{\n' + ',\n'.join(self.pdfinfo) + '\n}\n'
        else:
            pdfinfo = ''
        head = '\\title{%s}\n\\author{%s}\n\\date{%s}\n' % \
               (self.title,
                ' \\and\n'.join(['~\\\\\n'.join(author_lines)
                                 for author_lines in self.author_stack]),
                self.date)
        return ''.join(self.head_prefix + [head] + self.head + [pdfinfo]
                        + self.body_prefix  + self.body + self.body_suffix)

    def visit_Text(self, node):
        self.body.append(self.encode(node.astext()))

    def depart_Text(self, node):
        pass

    def visit_address(self, node):
        self.visit_docinfo_item(node, 'address')

    def depart_address(self, node):
        self.depart_docinfo_item(node)

    def visit_admonition(self, node, name=''):
        self.body.append('\\begin{center}\\begin{sffamily}\n')
        self.body.append('\\fbox{\\parbox{\\admonitionwidth}{\n')
        if name:
            self.body.append('\\textbf{\\large '+ self.language.labels[name] + '}\n');
        self.body.append('\\vspace{2mm}\n')


    def depart_admonition(self, node=None):
        self.body.append('}}\n') # end parbox fbox
        self.body.append('\\end{sffamily}\n\\end{center}\n');

    def visit_attention(self, node):
        self.visit_admonition(node, 'attention')

    def depart_attention(self, node):
        self.depart_admonition()

    def visit_author(self, node):
        self.visit_docinfo_item(node, 'author')

    def depart_author(self, node):
        self.depart_docinfo_item(node)

    def visit_authors(self, node):
        # not used: visit_author is called anyway for each author.
        pass

    def depart_authors(self, node):
        pass

    def visit_block_quote(self, node):
        self.body.append( '\\begin{quote}\n')

    def depart_block_quote(self, node):
        self.body.append( '\\end{quote}\n')

    def visit_bullet_list(self, node):
        if self.topic_classes == ['contents']:
            if not self.use_latex_toc:
                self.body.append( '\\begin{list}{}{}\n' )
        else:
            self.body.append( '\\begin{itemize}\n' )

    def depart_bullet_list(self, node):
        if self.topic_classes == ['contents']:
            if not self.use_latex_toc:
                self.body.append( '\\end{list}\n' )
        else:
            self.body.append( '\\end{itemize}\n' )

    # Imperfect superscript/subscript handling: mathmode italicizes
    # all letters by default.
    def visit_superscript(self, node):
        self.body.append('$^{')
        self.mathmode = 1

    def depart_superscript(self, node):
        self.body.append('}$')
        self.mathmode = 0

    def visit_subscript(self, node):
        self.body.append('$_{')
        self.mathmode = 1

    def depart_subscript(self, node):
        self.body.append('}$')
        self.mathmode = 0

    def visit_caption(self, node):
        self.body.append( '\\caption{' )

    def depart_caption(self, node):
        self.body.append('}')

    def visit_caution(self, node):
        self.visit_admonition(node, 'caution')

    def depart_caution(self, node):
        self.depart_admonition()

    def visit_title_reference(self, node):
        self.body.append( '\\titlereference{' )

    def depart_title_reference(self, node):
        self.body.append( '}' )

    def visit_citation(self, node):
        # TODO maybe use cite bibitems
        if self._use_latex_citations:
            self.context.append(len(self.body))
        else:
            self.body.append('\\begin{figure}[b]')
            for id in node['ids']:
                self.body.append('\\hypertarget{%s}' % id)

    def depart_citation(self, node):
        if self._use_latex_citations:
            size = self.context.pop()
            label = self.body[size]
            text = ''.join(self.body[size+1:])
            del self.body[size:]
            self._bibitems.append([label, text])
        else:
            self.body.append('\\end{figure}\n')

    def visit_citation_reference(self, node):
        if self._use_latex_citations:
            self.body.append('\\cite{')
        else:
            href = ''
            if node.has_key('refid'):
                href = node['refid']
            elif node.has_key('refname'):
                href = self.document.nameids[node['refname']]
            self.body.append('[\\hyperlink{%s}{' % href)

    def depart_citation_reference(self, node):
        if self._use_latex_citations:
            self.body.append('}')
        else:
            self.body.append('}]')

    def visit_classifier(self, node):
        self.body.append( '(\\textbf{' )

    def depart_classifier(self, node):
        self.body.append( '})\n' )

    def visit_colspec(self, node):
        self.active_table.visit_colspec(node)

    def depart_colspec(self, node):
        pass

    def visit_comment(self, node):
        # Escape end of line by a new comment start in comment text.
        self.body.append('%% %s \n' % node.astext().replace('\n', '\n% '))
        raise nodes.SkipNode

    def visit_compound(self, node):
        pass

    def depart_compound(self, node):
        pass

    def visit_contact(self, node):
        self.visit_docinfo_item(node, 'contact')

    def depart_contact(self, node):
        self.depart_docinfo_item(node)

    def visit_copyright(self, node):
        self.visit_docinfo_item(node, 'copyright')

    def depart_copyright(self, node):
        self.depart_docinfo_item(node)

    def visit_danger(self, node):
        self.visit_admonition(node, 'danger')

    def depart_danger(self, node):
        self.depart_admonition()

    def visit_date(self, node):
        self.visit_docinfo_item(node, 'date')

    def depart_date(self, node):
        self.depart_docinfo_item(node)

    def visit_decoration(self, node):
        pass

    def depart_decoration(self, node):
        pass

    def visit_definition(self, node):
        self.body.append('%[visit_definition]\n')

    def depart_definition(self, node):
        self.body.append('\n')
        self.body.append('%[depart_definition]\n')

    def visit_definition_list(self, node):
        self.body.append( '\\begin{description}\n' )

    def depart_definition_list(self, node):
        self.body.append( '\\end{description}\n' )

    def visit_definition_list_item(self, node):
        self.body.append('%[visit_definition_list_item]\n')

    def depart_definition_list_item(self, node):
        self.body.append('%[depart_definition_list_item]\n')

    def visit_description(self, node):
        if self.use_optionlist_for_option_list:
            self.body.append( ' ' )
        else:
            self.body.append( ' & ' )

    def depart_description(self, node):
        pass

    def visit_docinfo(self, node):
        self.docinfo = []
        self.docinfo.append('%' + '_'*75 + '\n')
        self.docinfo.append('\\begin{center}\n')
        self.docinfo.append('\\begin{tabularx}{\\docinfowidth}{lX}\n')

    def depart_docinfo(self, node):
        self.docinfo.append('\\end{tabularx}\n')
        self.docinfo.append('\\end{center}\n')
        self.body = self.docinfo + self.body
        # clear docinfo, so field names are no longer appended.
        self.docinfo = None

    def visit_docinfo_item(self, node, name):
        if name == 'author':
            if not self.pdfinfo == None:
                if not self.pdfauthor:
                    self.pdfauthor = self.attval(node.astext())
                else:
                    self.pdfauthor += self.author_separator + self.attval(node.astext())
        if self.use_latex_docinfo:
            if name in ('author', 'organization', 'contact', 'address'):
                # We attach these to the last author.  If any of them precedes
                # the first author, put them in a separate "author" group (for
                # no better semantics).
                if name == 'author' or not self.author_stack:
                    self.author_stack.append([])
                if name == 'address':   # newlines are meaningful
                    self.insert_newline = 1
                    text = self.encode(node.astext())
                    self.insert_newline = 0
                else:
                    text = self.attval(node.astext())
                self.author_stack[-1].append(text)
                raise nodes.SkipNode
            elif name == 'date':
                self.date = self.attval(node.astext())
                raise nodes.SkipNode
        self.docinfo.append('\\textbf{%s}: &\n\t' % self.language_label(name))
        if name == 'address':
            self.insert_newline = 1
            self.docinfo.append('{\\raggedright\n')
            self.context.append(' } \\\\\n')
        else:
            self.context.append(' \\\\\n')
        self.context.append(self.docinfo)
        self.context.append(len(self.body))

    def depart_docinfo_item(self, node):
        size = self.context.pop()
        dest = self.context.pop()
        tail = self.context.pop()
        tail = self.body[size:] + [tail]
        del self.body[size:]
        dest.extend(tail)
        # for address we did set insert_newline
        self.insert_newline = 0

    def visit_doctest_block(self, node):
        self.body.append( '\\begin{verbatim}' )
        self.verbatim = 1

    def depart_doctest_block(self, node):
        self.body.append( '\\end{verbatim}\n' )
        self.verbatim = 0

    def visit_document(self, node):
        self.body_prefix.append('\\begin{document}\n')
        # titled document?
        if self.use_latex_docinfo or len(node) and isinstance(node[0], nodes.title):
            self.body_prefix.append('\\maketitle\n\n')
            # alternative use titlepage environment.
            # \begin{titlepage}
        self.body.append('\n\\setlength{\\locallinewidth}{\\linewidth}\n')

    def depart_document(self, node):
        # TODO insertion point of bibliography should none automatic.
        if self._use_latex_citations and len(self._bibitems)>0:
            widest_label = ""
            for bi in self._bibitems:
                if len(widest_label) 14:
                self.body.append('\\multicolumn{2}{l}{')
                self.context.append('} \\\\\n  ')
            else:
                self.context.append('')
            self.body.append('\\texttt{')
        # flag for first option
        self.context.append(0)

    def depart_option_group(self, node):
        self.context.pop() # the flag
        if self.use_optionlist_for_option_list:
            self.body.append('] ')
        else:
            self.body.append('}')
            self.body.append(self.context.pop())

    def visit_option_list(self, node):
        self.body.append('% [option list]\n')
        if self.use_optionlist_for_option_list:
            self.body.append('\\begin{optionlist}{3cm}\n')
        else:
            self.body.append('\\begin{center}\n')
            # BUG: use admwidth or make it relative to textwidth ?
            self.body.append('\\begin{tabularx}{.9\\linewidth}{lX}\n')

    def depart_option_list(self, node):
        if self.use_optionlist_for_option_list:
            self.body.append('\\end{optionlist}\n')
        else:
            self.body.append('\\end{tabularx}\n')
            self.body.append('\\end{center}\n')

    def visit_option_list_item(self, node):
        pass

    def depart_option_list_item(self, node):
        if not self.use_optionlist_for_option_list:
            self.body.append('\\\\\n')

    def visit_option_string(self, node):
        ##self.body.append(self.starttag(node, 'span', '', CLASS='option'))
        pass

    def depart_option_string(self, node):
        ##self.body.append('')
        pass

    def visit_organization(self, node):
        self.visit_docinfo_item(node, 'organization')

    def depart_organization(self, node):
        self.depart_docinfo_item(node)

    def visit_paragraph(self, node):
        index = node.parent.index(node)
        if not (self.topic_classes == ['contents'] or
                (isinstance(node.parent, nodes.compound) and
                 index > 0 and
                 not isinstance(node.parent[index - 1], nodes.paragraph) and
                 not isinstance(node.parent[index - 1], nodes.compound))):
            self.body.append('\n')

    def depart_paragraph(self, node):
        self.body.append('\n')

    def visit_problematic(self, node):
        self.body.append('{\\color{red}\\bfseries{}')

    def depart_problematic(self, node):
        self.body.append('}')

    def visit_raw(self, node):
        if 'latex' in node.get('format', '').split():
            self.body.append(node.astext())
        raise nodes.SkipNode

    def visit_reference(self, node):
        # BUG: hash_char "#" is trouble some in LaTeX.
        # mbox and other environment do not like the '#'.
        hash_char = '\\#'
        if node.has_key('refuri'):
            href = node['refuri'].replace('#',hash_char)
        elif node.has_key('refid'):
            href = hash_char + node['refid']
        elif node.has_key('refname'):
            href = hash_char + self.document.nameids[node['refname']]
        else:
            raise AssertionError('Unknown reference.')
        self.body.append('\\href{%s}{' % href)

    def depart_reference(self, node):
        self.body.append('}')

    def visit_revision(self, node):
        self.visit_docinfo_item(node, 'revision')

    def depart_revision(self, node):
        self.depart_docinfo_item(node)

    def visit_section(self, node):
        self.section_level += 1
        # Initialize counter for potential subsections:
        self._section_number.append(0)
        # Counter for this section's level (initialized by parent section):
        self._section_number[self.section_level - 1] += 1

    def depart_section(self, node):
        # Remove counter for potential subsections:
        self._section_number.pop()
        self.section_level -= 1

    def visit_sidebar(self, node):
        # BUG:  this is just a hack to make sidebars render something
        self.body.append('\n\\setlength{\\locallinewidth}{0.9\\admonitionwidth}\n')
        self.body.append('\\begin{center}\\begin{sffamily}\n')
        self.body.append('\\fbox{\\colorbox[gray]{0.80}{\\parbox{\\admonitionwidth}{\n')

    def depart_sidebar(self, node):
        self.body.append('}}}\n') # end parbox colorbox fbox
        self.body.append('\\end{sffamily}\n\\end{center}\n');
        self.body.append('\n\\setlength{\\locallinewidth}{\\linewidth}\n')


    attribution_formats = {'dash': ('---', ''),
                           'parentheses': ('(', ')'),
                           'parens': ('(', ')'),
                           'none': ('', '')}

    def visit_attribution(self, node):
        prefix, suffix = self.attribution_formats[self.settings.attribution]
        self.body.append('\n\\begin{flushright}\n')
        self.body.append(prefix)
        self.context.append(suffix)

    def depart_attribution(self, node):
        self.body.append(self.context.pop() + '\n')
        self.body.append('\\end{flushright}\n')

    def visit_status(self, node):
        self.visit_docinfo_item(node, 'status')

    def depart_status(self, node):
        self.depart_docinfo_item(node)

    def visit_strong(self, node):
        self.body.append('\\textbf{')
        self.literal_block_stack.append('\\textbf{')

    def depart_strong(self, node):
        self.body.append('}')
        self.literal_block_stack.pop()

    def visit_substitution_definition(self, node):
        raise nodes.SkipNode

    def visit_substitution_reference(self, node):
        self.unimplemented_visit(node)

    def visit_subtitle(self, node):
        if isinstance(node.parent, nodes.sidebar):
            self.body.append('~\\\\\n\\textbf{')
            self.context.append('}\n\\smallskip\n')
        elif isinstance(node.parent, nodes.document):
            self.title = self.title + \
                '\\\\\n\\large{%s}\n' % self.encode(node.astext())
            raise nodes.SkipNode
        elif isinstance(node.parent, nodes.section):
            self.body.append('\\textbf{')
            self.context.append('}\\vspace{0.2cm}\n\n\\noindent ')

    def depart_subtitle(self, node):
        self.body.append(self.context.pop())

    def visit_system_message(self, node):
        if node['level'] < self.document.reporter.report_level:
            raise nodes.SkipNode

    def depart_system_message(self, node):
        self.body.append('\n')

    def visit_table(self, node):
        if self.active_table.is_open():
            print 'nested tables are not supported'
            raise AssertionError
        self.active_table.open()
        self.body.append('\n' + self.active_table.get_opening())

    def depart_table(self, node):
        self.body.append(self.active_table.get_closing() + '\n')
        self.active_table.close()

    def visit_target(self, node):
        # BUG: why not (refuri or refid or refname) means not footnote ?
        if not (node.has_key('refuri') or node.has_key('refid')
                or node.has_key('refname')):
            for id in node['ids']:
                self.body.append('\\hypertarget{%s}{' % id)
            self.context.append('}' * len(node['ids']))
        else:
            self.context.append('')

    def depart_target(self, node):
        self.body.append(self.context.pop())

    def visit_tbody(self, node):
        # BUG write preamble if not yet done (colspecs not [])
        # for tables without heads.
        if not self.active_table.get('preamble written'):
            self.visit_thead(None)
            # self.depart_thead(None)

    def depart_tbody(self, node):
        pass

    def visit_term(self, node):
        self.body.append('\\item[{')

    def depart_term(self, node):
        # definition list term.
        self.body.append('}] ')

    def visit_tgroup(self, node):
        #self.body.append(self.starttag(node, 'colgroup'))
        #self.context.append('\n')
        pass

    def depart_tgroup(self, node):
        pass

    def visit_thead(self, node):
        self.body.append('{%s}\n' % self.active_table.get_colspecs())
        if self.active_table.caption:
            self.body.append('\\caption{%s}\\\\\n' % self.active_table.caption)
        self.active_table.set('preamble written',1)
        # TODO longtable supports firsthead and lastfoot too.
        self.body.extend(self.active_table.visit_thead())

    def depart_thead(self, node):
        # the table header written should be on every page
        # => \endhead
        self.body.extend(self.active_table.depart_thead())
        # and the firsthead => \endfirsthead
        # BUG i want a "continued from previous page" on every not
        # firsthead, but then we need the header twice.
        #
        # there is a \endfoot and \endlastfoot too.
        # but we need the number of columns to
        # self.body.append('\\multicolumn{%d}{c}{"..."}\n' % number_of_columns)
        # self.body.append('\\hline\n\\endfoot\n')
        # self.body.append('\\hline\n')
        # self.body.append('\\endlastfoot\n')

    def visit_tip(self, node):
        self.visit_admonition(node, 'tip')

    def depart_tip(self, node):
        self.depart_admonition()

    def bookmark(self, node):
        """Append latex href and pdfbookmarks for titles.
        """
        if node.parent['ids']:
            for id in node.parent['ids']:
                self.body.append('\\hypertarget{%s}{}\n' % id)
            if not self.use_latex_toc:
                # BUG level depends on style. pdflatex allows level 0 to 3
                # ToC would be the only on level 0 so i choose to decrement the rest.
                # "Table of contents" bookmark to see the ToC. To avoid this
                # we set all zeroes to one.
                l = self.section_level
                if l>0:
                    l = l-1
                # pdftex does not like "_" subscripts in titles
                text = self.encode(node.astext())
                for id in node.parent['ids']:
                    self.body.append('\\pdfbookmark[%d]{%s}{%s}\n' % \
                                     (l, text, id))

    def visit_title(self, node):
        """Only 3 section levels are supported by LaTeX article (AFAIR)."""

        if isinstance(node.parent, nodes.topic):
            # section titles before the table of contents.
            self.bookmark(node)
            # BUG: latex chokes on center environment with "perhaps a missing item".
            # so we use hfill.
            self.body.append('\\subsubsection*{~\\hfill ')
            # the closing brace for subsection.
            self.context.append('\\hfill ~}\n')
        # TODO: for admonition titles before the first section
        # either specify every possible node or ... ?
        elif isinstance(node.parent, nodes.sidebar) \
        or isinstance(node.parent, nodes.admonition):
            self.body.append('\\textbf{\\large ')
            self.context.append('}\n\\smallskip\n')
        elif isinstance(node.parent, nodes.table):
            # caption must be written after column spec
            self.active_table.caption = self.encode(node.astext())
            raise nodes.SkipNode
        elif self.section_level == 0:
            # document title
            self.title = self.encode(node.astext())
            if not self.pdfinfo == None:
                self.pdfinfo.append( 'pdftitle={%s}' % self.encode(node.astext()) )
            raise nodes.SkipNode
        else:
            self.body.append('\n\n')
            self.body.append('%' + '_' * 75)
            self.body.append('\n\n')
            self.bookmark(node)

            if self.use_latex_toc:
                section_star = ""
            else:
                section_star = "*"

            section_name = self.d_class.section(self.section_level)
            self.body.append('\\%s%s{' % (section_name, section_star))

            self.context.append('}\n')

    def depart_title(self, node):
        self.body.append(self.context.pop())

    def visit_topic(self, node):
        self.topic_classes = node['classes']
        if 'contents' in node['classes'] and self.use_latex_toc:
            self.body.append('\\tableofcontents\n\n\\bigskip\n')
            self.topic_classes = []
            raise nodes.SkipNode

    def visit_inline(self, node): # titlereference
        self.body.append( '\\docutilsrole%s{' % node.get('class'))

    def depart_inline(self, node):
        self.body.append( '}' )

    def depart_topic(self, node):
        self.topic_classes = []
        self.body.append('\n')

    def visit_rubric(self, node):
        self.body.append('\\rubric{')
        self.context.append('}\n')

    def depart_rubric(self, node):
        self.body.append(self.context.pop())

    def visit_transition(self, node):
        self.body.append('\n\n')
        self.body.append('%' + '_' * 75)
        self.body.append('\n\\hspace*{\\fill}\\hrulefill\\hspace*{\\fill}')
        self.body.append('\n\n')

    def depart_transition(self, node):
        pass

    def visit_version(self, node):
        self.visit_docinfo_item(node, 'version')

    def depart_version(self, node):
        self.depart_docinfo_item(node)

    def visit_warning(self, node):
        self.visit_admonition(node, 'warning')

    def depart_warning(self, node):
        self.depart_admonition()

    def unimplemented_visit(self, node):
        raise NotImplementedError('visiting unimplemented node type: %s'
                                  % node.__class__.__name__)

#    def unknown_visit(self, node):
#    def default_visit(self, node):

# vim: set ts=4 et ai :
Zope-2.9.4-retire_zpkg/lib/python/docutils/urischemes.py0000644000175000017500000001227510172235404023335 0ustar  tseavertseaver"""
`schemes` is a dictionary with lowercase URI addressing schemes as
keys and descriptions as values. It was compiled from the index at
http://www.iana.org/assignments/uri-schemes (revised 2003-11-26)
and an older list at http://www.w3.org/Addressing/schemes.html.
"""

# Many values are blank and should be filled in with useful descriptions.

schemes = {
      'about': 'provides information on Navigator',
      'acap': 'Application Configuration Access Protocol',
      'addbook': "To add vCard entries to Communicator's Address Book",
      'afp': 'Apple Filing Protocol',
      'afs': 'Andrew File System global file names',
      'aim': 'AOL Instant Messenger',
      'callto': 'for NetMeeting links',
      'castanet': 'Castanet Tuner URLs for Netcaster',
      'chttp': 'cached HTTP supported by RealPlayer',
      'cid': 'content identifier',
      'data': ('allows inclusion of small data items as "immediate" data; '
               'RFC 2397'),
      'dav': 'Distributed Authoring and Versioning Protocol; RFC 2518',
      'dns': 'Domain Name System resources',
      'eid': ('External ID; non-URL data; general escape mechanism to allow '
              'access to information for applications that are too '
              'specialized to justify their own schemes'),
      'fax': ('a connection to a terminal that can handle telefaxes '
              '(facsimiles); RFC 2806'),
      'feed' : 'NetNewsWire feed',
      'file': 'Host-specific file names',
      'finger': '',
      'freenet': '',
      'ftp': 'File Transfer Protocol',
      'go': 'go; RFC3368',
      'gopher': 'The Gopher Protocol',
      'gsm-sms': ('Global System for Mobile Communications Short Message '
                  'Service'),
      'h323': 'video (audiovisual) communication on local area networks',
      'h324': ('video and audio communications over low bitrate connections '
               'such as POTS modem connections'),
      'hdl': 'CNRI handle system',
      'hnews': 'an HTTP-tunneling variant of the NNTP news protocol',
      'http': 'Hypertext Transfer Protocol',
      'https': 'HTTP over SSL',
      'hydra': 'SubEthaEdit URI.  See http://www.codingmonkeys.de/subethaedit.',
      'iioploc': 'Internet Inter-ORB Protocol Location?',
      'ilu': 'Inter-Language Unification',
      'im': 'Instant Messaging',
      'imap': 'Internet Message Access Protocol',
      'ior': 'CORBA interoperable object reference',
      'ipp': 'Internet Printing Protocol',
      'irc': 'Internet Relay Chat',
      'iseek' : 'See www.ambrosiasw.com;  a little util for OS X.',
      'jar': 'Java archive',
      'javascript': ('JavaScript code; evaluates the expression after the '
                     'colon'),
      'jdbc': 'JDBC connection URI.',
      'ldap': 'Lightweight Directory Access Protocol',
      'lifn': '',
      'livescript': '',
      'lrq': '',
      'mailbox': 'Mail folder access',
      'mailserver': 'Access to data available from mail servers',
      'mailto': 'Electronic mail address',
      'md5': '',
      'mid': 'message identifier',
      'mocha': '',
      'modem': ('a connection to a terminal that can handle incoming data '
                'calls; RFC 2806'),
      'mupdate': 'Mailbox Update (MUPDATE) Protocol',
      'news': 'USENET news',
      'nfs': 'Network File System protocol',
      'nntp': 'USENET news using NNTP access',
      'opaquelocktoken': '',
      'phone': '',
      'pop': 'Post Office Protocol',
      'pop3': 'Post Office Protocol v3',
      'pres': 'Presence',
      'printer': '',
      'prospero': 'Prospero Directory Service',
      'rdar' : 'URLs found in Darwin source (http://www.opensource.apple.com/darwinsource/).',
      'res': '',
      'rtsp': 'real time streaming protocol',
      'rvp': '',
      'rwhois': '',
      'rx': 'Remote Execution',
      'sdp': '',
      'service': 'service location',
      'shttp': 'secure hypertext transfer protocol',
      'sip': 'Session Initiation Protocol',
      'sips': 'secure session intitiaion protocol',
      'smb': 'SAMBA filesystems.',
      'snews': 'For NNTP postings via SSL',
      'soap.beep': '',
      'soap.beeps': '',
      'ssh': 'Reference to interactive sessions via ssh.',
      't120': 'real time data conferencing (audiographics)',
      'tcp': '',
      'tel': ('a connection to a terminal that handles normal voice '
              'telephone calls, a voice mailbox or another voice messaging '
              'system or a service that can be operated using DTMF tones; '
              'RFC 2806.'),
      'telephone': 'telephone',
      'telnet': 'Reference to interactive sessions',
      'tftp': 'Trivial File Transfer Protocol',
      'tip': 'Transaction Internet Protocol',
      'tn3270': 'Interactive 3270 emulation sessions',
      'tv': '',
      'urn': 'Uniform Resource Name',
      'uuid': '',
      'vemmi': 'versatile multimedia interface',
      'videotex': '',
      'view-source': 'displays HTML code that was generated with JavaScript',
      'wais': 'Wide Area Information Servers',
      'whodp': '',
      'whois++': 'Distributed directory service.',
      'x-man-page': 'Opens man page in Terminal.app on OS X (see macosxhints.com)',
      'xmlrpc.beep': '',
      'xmlrpc.beeps': '',
      'z39.50r': 'Z39.50 Retrieval',
      'z39.50s': 'Z39.50 Session',}
Zope-2.9.4-retire_zpkg/lib/python/docutils/nodes.py0000644000175000017500000015616210322224711022276 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3358 $
# Date: $Date: 2005-05-21 02:00:25 +0200 (Sat, 21 May 2005) $
# Copyright: This module has been placed in the public domain.

"""
Docutils document tree element class library.

Classes in CamelCase are abstract base classes or auxiliary classes. The one
exception is `Text`, for a text (PCDATA) node; uppercase is used to
differentiate from element classes.  Classes in lower_case_with_underscores
are element classes, matching the XML element generic identifiers in the DTD_.

The position of each node (the level at which it can occur) is significant and
is represented by abstract base classes (`Root`, `Structural`, `Body`,
`Inline`, etc.).  Certain transformations will be easier because we can use
``isinstance(node, base_class)`` to determine the position of the node in the
hierarchy.

.. _DTD: http://docutils.sourceforge.net/docs/ref/docutils.dtd
"""

__docformat__ = 'reStructuredText'

import sys
import os
import re
import copy
import warnings
import xml.dom.minidom
from types import IntType, SliceType, StringType, UnicodeType, \
     TupleType, ListType
from UserString import UserString


# ==============================
#  Functional Node Base Classes
# ==============================

class Node:

    """Abstract base class of nodes in a document tree."""

    parent = None
    """Back-reference to the Node immediately containing this Node."""

    document = None
    """The `document` node at the root of the tree containing this Node."""

    source = None
    """Path or description of the input source which generated this Node."""

    line = None
    """The line number (1-based) of the beginning of this Node in `source`."""

    def __nonzero__(self):
        """
        Node instances are always true, even if they're empty.  A node is more
        than a simple container.  Its boolean "truth" does not depend on
        having one or more subnodes in the doctree.

        Use `len()` to check node length.  Use `None` to represent a boolean
        false value.
        """
        return 1

    def asdom(self, dom=xml.dom.minidom):
        """Return a DOM **fragment** representation of this Node."""
        domroot = dom.Document()
        return self._dom_node(domroot)

    def pformat(self, indent='    ', level=0):
        """
        Return an indented pseudo-XML representation, for test purposes.

        Override in subclasses.
        """
        raise NotImplementedError

    def copy(self):
        """Return a copy of self."""
        raise NotImplementedError

    def setup_child(self, child):
        child.parent = self
        if self.document:
            child.document = self.document
            if child.source is None:
                child.source = self.document.current_source
            if child.line is None:
                child.line = self.document.current_line

    def walk(self, visitor):
        """
        Traverse a tree of `Node` objects, calling the
        `dispatch_visit()` method of `visitor` when entering each
        node.  (The `walkabout()` method is similar, except it also
        calls the `dispatch_departure()` method before exiting each
        node.)

        This tree traversal supports limited in-place tree
        modifications.  Replacing one node with one or more nodes is
        OK, as is removing an element.  However, if the node removed
        or replaced occurs after the current node, the old node will
        still be traversed, and any new nodes will not.

        Within ``visit`` methods (and ``depart`` methods for
        `walkabout()`), `TreePruningException` subclasses may be raised
        (`SkipChildren`, `SkipSiblings`, `SkipNode`, `SkipDeparture`).

        Parameter `visitor`: A `NodeVisitor` object, containing a
        ``visit`` implementation for each `Node` subclass encountered.
        """
        visitor.document.reporter.debug(
            'docutils.nodes.Node.walk calling dispatch_visit for %s'
            % self.__class__.__name__)
        try:
            visitor.dispatch_visit(self)
        except (SkipChildren, SkipNode):
            return
        except SkipDeparture:           # not applicable; ignore
            pass
        children = self.children
        try:
            for child in children[:]:
                child.walk(visitor)
        except SkipSiblings:
            pass

    def walkabout(self, visitor):
        """
        Perform a tree traversal similarly to `Node.walk()` (which
        see), except also call the `dispatch_departure()` method
        before exiting each node.

        Parameter `visitor`: A `NodeVisitor` object, containing a
        ``visit`` and ``depart`` implementation for each `Node`
        subclass encountered.
        """
        call_depart = 1
        visitor.document.reporter.debug(
            'docutils.nodes.Node.walkabout calling dispatch_visit for %s'
            % self.__class__.__name__)
        try:
            try:
                visitor.dispatch_visit(self)
            except SkipNode:
                return
            except SkipDeparture:
                call_depart = 0
            children = self.children
            try:
                for child in children[:]:
                    child.walkabout(visitor)
            except SkipSiblings:
                pass
        except SkipChildren:
            pass
        if call_depart:
            visitor.document.reporter.debug(
                'docutils.nodes.Node.walkabout calling dispatch_departure '
                'for %s' % self.__class__.__name__)
            visitor.dispatch_departure(self)

    def traverse(self, condition=None,
                 include_self=1, descend=1, siblings=0, ascend=0):
        """
        Return an iterable containing

        * self (if include_self is true)
        * all descendants in tree traversal order (if descend is true)
        * all siblings (if siblings is true) and their descendants (if
          also descend is true)
        * the siblings of the parent (if ascend is true) and their
          descendants (if also descend is true), and so on

        If ascend is true, assume siblings to be true as well.

        For example, given the following tree::

            
                      <--- emphasis.traverse() and
                        <--- strong.traverse() are called.
                        Foo
                    Bar
                
                    Baz

        Then list(emphasis.traverse()) equals ::

            [, , <#text: Foo>, <#text: Bar>]

        and list(strong.traverse(ascend=1)) equals ::

            [, <#text: Foo>, <#text: Bar>, , <#text: Baz>]
        """
        r = []
        if ascend:
            siblings=1
        if include_self and (condition is None or condition(self)):
            r.append(self)
        if descend and len(self.children):
            for child in self:
                r.extend(child.traverse(
                    include_self=1, descend=1, siblings=0, ascend=0,
                    condition=condition))
        if siblings or ascend:
            node = self
            while node.parent:
                index = node.parent.index(node)
                for sibling in node.parent[index+1:]:
                    r.extend(sibling.traverse(include_self=1, descend=descend,
                                              siblings=0, ascend=0,
                                              condition=condition))
                if not ascend:
                    break
                else:
                    node = node.parent
        return r


    def next_node(self, condition=None,
                  include_self=0, descend=1, siblings=0, ascend=0):
        """
        Return the first node in the iterable returned by traverse(),
        or None if the iterable is empty.

        Parameter list is the same as of traverse.  Note that
        include_self defaults to 0, though.
        """
        iterable = self.traverse(condition=condition,
                                 include_self=include_self, descend=descend,
                                 siblings=siblings, ascend=ascend)
        try:
            return iterable[0]
        except IndexError:
            return None

class Text(Node, UserString):

    """
    Instances are terminal nodes (leaves) containing text only; no child
    nodes or attributes.  Initialize by passing a string to the constructor.
    Access the text itself with the `astext` method.
    """

    tagname = '#text'

    children = ()
    """Text nodes have no children, and cannot have children."""

    def __init__(self, data, rawsource=''):
        UserString.__init__(self, data)

        self.rawsource = rawsource
        """The raw text from which this element was constructed."""

    def __repr__(self):
        data = repr(self.data)
        if len(data) > 70:
            data = repr(self.data[:64] + ' ...')
        return '<%s: %s>' % (self.tagname, data)

    def __len__(self):
        return len(self.data)

    def shortrepr(self):
        data = repr(self.data)
        if len(data) > 20:
            data = repr(self.data[:16] + ' ...')
        return '<%s: %s>' % (self.tagname, data)

    def _dom_node(self, domroot):
        return domroot.createTextNode(self.data)

    def astext(self):
        return self.data

    def copy(self):
        return self.__class__(self.data)

    def pformat(self, indent='    ', level=0):
        result = []
        indent = indent * level
        for line in self.data.splitlines():
            result.append(indent + line + '\n')
        return ''.join(result)


class Element(Node):

    """
    `Element` is the superclass to all specific elements.

    Elements contain attributes and child nodes.  Elements emulate
    dictionaries for attributes, indexing by attribute name (a string).  To
    set the attribute 'att' to 'value', do::

        element['att'] = 'value'

    There are two special attributes: 'ids' and 'names'.  Both are
    lists of unique identifiers, and names serve as human interfaces
    to IDs.  Names are case- and whitespace-normalized (see the
    fully_normalize_name() function), and IDs conform to the regular
    expression ``[a-z](-?[a-z0-9]+)*`` (see the make_id() function).

    Elements also emulate lists for child nodes (element nodes and/or text
    nodes), indexing by integer.  To get the first child node, use::

        element[0]

    Elements may be constructed using the ``+=`` operator.  To add one new
    child node to element, do::

        element += node

    This is equivalent to ``element.append(node)``.

    To add a list of multiple child nodes at once, use the same ``+=``
    operator::

        element += [node1, node2]

    This is equivalent to ``element.extend([node1, node2])``.
    """

    attr_defaults = {'ids': [], 'classes': [], 'names': [],
                     'dupnames': [], 'backrefs': []}
    """Default attributes."""

    tagname = None
    """The element generic identifier. If None, it is set as an instance
    attribute to the name of the class."""

    child_text_separator = '\n\n'
    """Separator for child nodes, used by `astext()` method."""

    def __init__(self, rawsource='', *children, **attributes):
        self.rawsource = rawsource
        """The raw text from which this element was constructed."""

        self.children = []
        """List of child nodes (elements and/or `Text`)."""

        self.extend(children)           # maintain parent info

        self.attributes = copy.deepcopy(self.attr_defaults)
        """Dictionary of attribute {name: value}."""

        for att, value in attributes.items():
            self.attributes[att.lower()] = value

        if self.tagname is None:
            self.tagname = self.__class__.__name__

    def _dom_node(self, domroot):
        element = domroot.createElement(self.tagname)
        for attribute, value in self.attlist():
            if isinstance(value, ListType):
                value = ' '.join(['%s' % v for v in value])
            element.setAttribute(attribute, '%s' % value)
        for child in self.children:
            element.appendChild(child._dom_node(domroot))
        return element

    def __repr__(self):
        data = ''
        for c in self.children:
            data += c.shortrepr()
            if len(data) > 60:
                data = data[:56] + ' ...'
                break
        if self['names']:
            return '<%s "%s": %s>' % (self.__class__.__name__,
                                      '; '.join(self['names']), data)
        else:
            return '<%s: %s>' % (self.__class__.__name__, data)

    def shortrepr(self):
        if self['names']:
            return '<%s "%s"...>' % (self.__class__.__name__,
                                     '; '.join(self['names']))
        else:
            return '<%s...>' % self.tagname

    def __str__(self):
        return self.__unicode__().encode('raw_unicode_escape')

    def __unicode__(self):
        if self.children:
            return u'%s%s%s' % (self.starttag(),
                                 ''.join([str(c) for c in self.children]),
                                 self.endtag())
        else:
            return self.emptytag()

    def starttag(self):
        parts = [self.tagname]
        for name, value in self.attlist():
            if value is None:           # boolean attribute
                parts.append(name)
            elif isinstance(value, ListType):
                values = ['%s' % v for v in value]
                parts.append('%s="%s"' % (name, ' '.join(values)))
            else:
                parts.append('%s="%s"' % (name, value))
        return '<%s>' % ' '.join(parts)

    def endtag(self):
        return '' % self.tagname

    def emptytag(self):
        return u'<%s/>' % ' '.join([self.tagname] +
                                    ['%s="%s"' % (n, v)
                                     for n, v in self.attlist()])

    def __len__(self):
        return len(self.children)

    def __getitem__(self, key):
        if isinstance(key, UnicodeType) or isinstance(key, StringType):
            return self.attributes[key]
        elif isinstance(key, IntType):
            return self.children[key]
        elif isinstance(key, SliceType):
            assert key.step in (None, 1), 'cannot handle slice with stride'
            return self.children[key.start:key.stop]
        else:
            raise TypeError, ('element index must be an integer, a slice, or '
                              'an attribute name string')

    def __setitem__(self, key, item):
        if isinstance(key, UnicodeType) or isinstance(key, StringType):
            self.attributes[str(key)] = item
        elif isinstance(key, IntType):
            self.setup_child(item)
            self.children[key] = item
        elif isinstance(key, SliceType):
            assert key.step in (None, 1), 'cannot handle slice with stride'
            for node in item:
                self.setup_child(node)
            self.children[key.start:key.stop] = item
        else:
            raise TypeError, ('element index must be an integer, a slice, or '
                              'an attribute name string')

    def __delitem__(self, key):
        if isinstance(key, UnicodeType) or isinstance(key, StringType):
            del self.attributes[key]
        elif isinstance(key, IntType):
            del self.children[key]
        elif isinstance(key, SliceType):
            assert key.step in (None, 1), 'cannot handle slice with stride'
            del self.children[key.start:key.stop]
        else:
            raise TypeError, ('element index must be an integer, a simple '
                              'slice, or an attribute name string')

    def __add__(self, other):
        return self.children + other

    def __radd__(self, other):
        return other + self.children

    def __iadd__(self, other):
        """Append a node or a list of nodes to `self.children`."""
        if isinstance(other, Node):
            self.append(other)
        elif other is not None:
            self.extend(other)
        return self

    def astext(self):
        return self.child_text_separator.join(
              [child.astext() for child in self.children])

    def non_default_attributes(self):
        atts = {}
        for key, value in self.attributes.items():
            if self.is_not_default(key):
                atts[key] = value
        return atts

    def attlist(self):
        attlist = self.non_default_attributes().items()
        attlist.sort()
        return attlist

    def get(self, key, failobj=None):
        return self.attributes.get(key, failobj)

    def hasattr(self, attr):
        return self.attributes.has_key(attr)

    def delattr(self, attr):
        if self.attributes.has_key(attr):
            del self.attributes[attr]

    def setdefault(self, key, failobj=None):
        return self.attributes.setdefault(key, failobj)

    has_key = hasattr

    def append(self, item):
        self.setup_child(item)
        self.children.append(item)

    def extend(self, item):
        for node in item:
            self.append(node)

    def insert(self, index, item):
        if isinstance(item, Node):
            self.setup_child(item)
            self.children.insert(index, item)
        elif item is not None:
            self[index:index] = item

    def pop(self, i=-1):
        return self.children.pop(i)

    def remove(self, item):
        self.children.remove(item)

    def index(self, item):
        return self.children.index(item)

    def is_not_default(self, key):
        try:
            return self[key] != self.attr_defaults[key]
        except KeyError:
            return 1

    def clear(self):
        self.children = []

    def replace(self, old, new):
        """Replace one child `Node` with another child or children."""
        index = self.index(old)
        if isinstance(new, Node):
            self.setup_child(new)
            self[index] = new
        elif new is not None:
            self[index:index+1] = new

    def first_child_matching_class(self, childclass, start=0, end=sys.maxint):
        """
        Return the index of the first child whose class exactly matches.

        Parameters:

        - `childclass`: A `Node` subclass to search for, or a tuple of `Node`
          classes. If a tuple, any of the classes may match.
        - `start`: Initial index to check.
        - `end`: Initial index to *not* check.
        """
        if not isinstance(childclass, TupleType):
            childclass = (childclass,)
        for index in range(start, min(len(self), end)):
            for c in childclass:
                if isinstance(self[index], c):
                    return index
        return None

    def first_child_not_matching_class(self, childclass, start=0,
                                       end=sys.maxint):
        """
        Return the index of the first child whose class does *not* match.

        Parameters:

        - `childclass`: A `Node` subclass to skip, or a tuple of `Node`
          classes. If a tuple, none of the classes may match.
        - `start`: Initial index to check.
        - `end`: Initial index to *not* check.
        """
        if not isinstance(childclass, TupleType):
            childclass = (childclass,)
        for index in range(start, min(len(self), end)):
            for c in childclass:
                if isinstance(self.children[index], c):
                    break
            else:
                return index
        return None

    def pformat(self, indent='    ', level=0):
        return ''.join(['%s%s\n' % (indent * level, self.starttag())] +
                       [child.pformat(indent, level+1)
                        for child in self.children])

    def copy(self):
        return self.__class__(**self.attributes)

    def set_class(self, name):
        """Add a new class to the "classes" attribute."""
        warnings.warn('docutils.nodes.Element.set_class deprecated; '
                      "append to Element['classes'] list attribute directly",
                      DeprecationWarning, stacklevel=2)
        assert ' ' not in name
        self['classes'].append(name.lower())

    def note_referenced_by(self, name=None, id=None):
        """Note that this Element has been referenced by its name
        `name` or id `id`."""
        self.referenced = 1
        # Element.expect_referenced_by_* dictionaries map names or ids
        # to nodes whose ``referenced`` attribute is set to true as
        # soon as this node is referenced by the given name or id.
        # Needed for target propagation.
        by_name = getattr(self, 'expect_referenced_by_name', {}).get(name)
        by_id = getattr(self, 'expect_referenced_by_id', {}).get(id)
        if by_name:
            assert name is not None
            by_name.referenced = 1
        if by_id:
            assert id is not None
            by_id.referenced = 1


class TextElement(Element):

    """
    An element which directly contains text.

    Its children are all `Text` or `Inline` subclass nodes.  You can
    check whether an element's context is inline simply by checking whether
    its immediate parent is a `TextElement` instance (including subclasses).
    This is handy for nodes like `image` that can appear both inline and as
    standalone body elements.

    If passing children to `__init__()`, make sure to set `text` to
    ``''`` or some other suitable value.
    """

    child_text_separator = ''
    """Separator for child nodes, used by `astext()` method."""

    def __init__(self, rawsource='', text='', *children, **attributes):
        if text != '':
            textnode = Text(text)
            Element.__init__(self, rawsource, textnode, *children,
                              **attributes)
        else:
            Element.__init__(self, rawsource, *children, **attributes)


class FixedTextElement(TextElement):

    """An element which directly contains preformatted text."""

    def __init__(self, rawsource='', text='', *children, **attributes):
        TextElement.__init__(self, rawsource, text, *children, **attributes)
        self.attributes['xml:space'] = 'preserve'


# ========
#  Mixins
# ========

class Resolvable:

    resolved = 0


class BackLinkable:

    def add_backref(self, refid):
        self['backrefs'].append(refid)


# ====================
#  Element Categories
# ====================

class Root: pass

class Titular: pass

class PreBibliographic:
    """Category of Node which may occur before Bibliographic Nodes."""

class Bibliographic: pass

class Decorative(PreBibliographic): pass

class Structural: pass

class Body: pass

class General(Body): pass

class Sequential(Body):
    """List-like elements."""

class Admonition(Body): pass

class Special(Body):
    """Special internal body elements."""

class Invisible(PreBibliographic):
    """Internal elements that don't appear in output."""

class Part: pass

class Inline: pass

class Referential(Resolvable): pass

class Targetable(Resolvable):

    referenced = 0

class Labeled:
    """Contains a `label` as its first element."""


# ==============
#  Root Element
# ==============

class document(Root, Structural, Element):

    def __init__(self, settings, reporter, *args, **kwargs):
        Element.__init__(self, *args, **kwargs)

        self.current_source = None
        """Path to or description of the input source being processed."""

        self.current_line = None
        """Line number (1-based) of `current_source`."""

        self.settings = settings
        """Runtime settings data record."""

        self.reporter = reporter
        """System message generator."""

        self.external_targets = []
        """List of external target nodes."""

        self.internal_targets = []
        """List of internal target nodes."""

        self.indirect_targets = []
        """List of indirect target nodes."""

        self.substitution_defs = {}
        """Mapping of substitution names to substitution_definition nodes."""

        self.substitution_names = {}
        """Mapping of case-normalized substitution names to case-sensitive
        names."""

        self.refnames = {}
        """Mapping of names to lists of referencing nodes."""

        self.refids = {}
        """Mapping of ids to lists of referencing nodes."""

        self.nameids = {}
        """Mapping of names to unique id's."""

        self.nametypes = {}
        """Mapping of names to hyperlink type (boolean: True => explicit,
        False => implicit."""

        self.ids = {}
        """Mapping of ids to nodes."""

        self.substitution_refs = {}
        """Mapping of substitution names to lists of substitution_reference
        nodes."""

        self.footnote_refs = {}
        """Mapping of footnote labels to lists of footnote_reference nodes."""

        self.citation_refs = {}
        """Mapping of citation labels to lists of citation_reference nodes."""

        self.anonymous_targets = []
        """List of anonymous target nodes."""

        self.anonymous_refs = []
        """List of anonymous reference nodes."""

        self.autofootnotes = []
        """List of auto-numbered footnote nodes."""

        self.autofootnote_refs = []
        """List of auto-numbered footnote_reference nodes."""

        self.symbol_footnotes = []
        """List of symbol footnote nodes."""

        self.symbol_footnote_refs = []
        """List of symbol footnote_reference nodes."""

        self.footnotes = []
        """List of manually-numbered footnote nodes."""

        self.citations = []
        """List of citation nodes."""

        self.autofootnote_start = 1
        """Initial auto-numbered footnote number."""

        self.symbol_footnote_start = 0
        """Initial symbol footnote symbol index."""

        self.id_start = 1
        """Initial ID number."""

        self.parse_messages = []
        """System messages generated while parsing."""

        self.transform_messages = []
        """System messages generated while applying transforms."""

        import docutils.transforms
        self.transformer = docutils.transforms.Transformer(self)
        """Storage for transforms to be applied to this document."""

        self.decoration = None
        """Document's `decoration` node."""

        self.document = self

    def asdom(self, dom=xml.dom.minidom):
        """Return a DOM representation of this document."""
        domroot = dom.Document()
        domroot.appendChild(self._dom_node(domroot))
        return domroot

    def set_id(self, node, msgnode=None):
        for id in node['ids']:
            if self.ids.has_key(id) and self.ids[id] is not node:
                msg = self.reporter.severe('Duplicate ID: "%s".' % id)
                if msgnode != None:
                    msgnode += msg
        if not node['ids']:
            for name in node['names']:
                id = self.settings.id_prefix + make_id(name)
                if id and not self.ids.has_key(id):
                    break
            else:
                id = ''
                while not id or self.ids.has_key(id):
                    id = (self.settings.id_prefix +
                          self.settings.auto_id_prefix + str(self.id_start))
                    self.id_start += 1
            node['ids'].append(id)
        self.ids[id] = node
        return id

    def set_name_id_map(self, node, id, msgnode=None, explicit=None):
        """
        `self.nameids` maps names to IDs, while `self.nametypes` maps names to
        booleans representing hyperlink type (True==explicit,
        False==implicit).  This method updates the mappings.

        The following state transition table shows how `self.nameids` ("ids")
        and `self.nametypes` ("types") change with new input (a call to this
        method), and what actions are performed:

        ====  =====  ========  ========  =======  ====  =====  =====
         Old State    Input          Action        New State   Notes
        -----------  --------  -----------------  -----------  -----
        ids   types  new type  sys.msg.  dupname  ids   types
        ====  =====  ========  ========  =======  ====  =====  =====
        --    --     explicit  --        --       new   True
        --    --     implicit  --        --       new   False
        None  False  explicit  --        --       new   True
        old   False  explicit  implicit  old      new   True
        None  True   explicit  explicit  new      None  True
        old   True   explicit  explicit  new,old  None  True   [#]_
        None  False  implicit  implicit  new      None  False
        old   False  implicit  implicit  new,old  None  False
        None  True   implicit  implicit  new      None  True
        old   True   implicit  implicit  new      old   True
        ====  =====  ========  ========  =======  ====  =====  =====

        .. [#] Do not clear the name-to-id map or invalidate the old target if
           both old and new targets are external and refer to identical URIs.
           The new target is invalidated regardless.
        """
        for name in node['names']:
            if self.nameids.has_key(name):
                self.set_duplicate_name_id(node, id, name, msgnode, explicit)
            else:
                self.nameids[name] = id
                self.nametypes[name] = explicit

    def set_duplicate_name_id(self, node, id, name, msgnode, explicit):
        old_id = self.nameids[name]
        old_explicit = self.nametypes[name]
        self.nametypes[name] = old_explicit or explicit
        if explicit:
            if old_explicit:
                level = 2
                if old_id is not None:
                    old_node = self.ids[old_id]
                    if node.has_key('refuri'):
                        refuri = node['refuri']
                        if old_node['names'] \
                               and old_node.has_key('refuri') \
                               and old_node['refuri'] == refuri:
                            level = 1   # just inform if refuri's identical
                    if level > 1:
                        dupname(old_node, name)
                        self.nameids[name] = None
                msg = self.reporter.system_message(
                    level, 'Duplicate explicit target name: "%s".' % name,
                    backrefs=[id], base_node=node)
                if msgnode != None:
                    msgnode += msg
                dupname(node, name)
            else:
                self.nameids[name] = id
                if old_id is not None:
                    old_node = self.ids[old_id]
                    dupname(old_node, name)
        else:
            if old_id is not None and not old_explicit:
                self.nameids[name] = None
                old_node = self.ids[old_id]
                dupname(old_node, name)
            dupname(node, name)
        if not explicit or (not old_explicit and old_id is not None):
            msg = self.reporter.info(
                'Duplicate implicit target name: "%s".' % name,
                backrefs=[id], base_node=node)
            if msgnode != None:
                msgnode += msg

    def has_name(self, name):
        return self.nameids.has_key(name)

    # "note" here is an imperative verb: "take note of".
    def note_implicit_target(self, target, msgnode=None):
        id = self.set_id(target, msgnode)
        self.set_name_id_map(target, id, msgnode, explicit=None)

    def note_explicit_target(self, target, msgnode=None):
        id = self.set_id(target, msgnode)
        self.set_name_id_map(target, id, msgnode, explicit=1)

    def note_refname(self, node):
        self.refnames.setdefault(node['refname'], []).append(node)

    def note_refid(self, node):
        self.refids.setdefault(node['refid'], []).append(node)

    def note_external_target(self, target):
        self.external_targets.append(target)

    def note_internal_target(self, target):
        self.internal_targets.append(target)

    def note_indirect_target(self, target):
        self.indirect_targets.append(target)
        if target['names']:
            self.note_refname(target)

    def note_anonymous_target(self, target):
        self.set_id(target)
        self.anonymous_targets.append(target)

    def note_anonymous_ref(self, ref):
        self.anonymous_refs.append(ref)

    def note_autofootnote(self, footnote):
        self.set_id(footnote)
        self.autofootnotes.append(footnote)

    def note_autofootnote_ref(self, ref):
        self.set_id(ref)
        self.autofootnote_refs.append(ref)

    def note_symbol_footnote(self, footnote):
        self.set_id(footnote)
        self.symbol_footnotes.append(footnote)

    def note_symbol_footnote_ref(self, ref):
        self.set_id(ref)
        self.symbol_footnote_refs.append(ref)

    def note_footnote(self, footnote):
        self.set_id(footnote)
        self.footnotes.append(footnote)

    def note_footnote_ref(self, ref):
        self.set_id(ref)
        self.footnote_refs.setdefault(ref['refname'], []).append(ref)
        self.note_refname(ref)

    def note_citation(self, citation):
        self.citations.append(citation)

    def note_citation_ref(self, ref):
        self.set_id(ref)
        self.citation_refs.setdefault(ref['refname'], []).append(ref)
        self.note_refname(ref)

    def note_substitution_def(self, subdef, def_name, msgnode=None):
        name = whitespace_normalize_name(def_name)
        subdef['names'].append(name)
        if self.substitution_defs.has_key(name):
            msg = self.reporter.error(
                  'Duplicate substitution definition name: "%s".' % name,
                  base_node=subdef)
            if msgnode != None:
                msgnode += msg
            oldnode = self.substitution_defs[name]
            dupname(oldnode, name)
        # keep only the last definition:
        self.substitution_defs[name] = subdef
        # case-insensitive mapping:
        self.substitution_names[fully_normalize_name(name)] = name

    def note_substitution_ref(self, subref, refname):
        name = subref['refname'] = whitespace_normalize_name(refname)
        self.substitution_refs.setdefault(name, []).append(subref)

    def note_pending(self, pending, priority=None):
        self.transformer.add_pending(pending, priority)

    def note_parse_message(self, message):
        self.parse_messages.append(message)

    def note_transform_message(self, message):
        self.transform_messages.append(message)

    def note_source(self, source, offset):
        self.current_source = source
        if offset is None:
            self.current_line = offset
        else:
            self.current_line = offset + 1

    def copy(self):
        return self.__class__(self.settings, self.reporter,
                              **self.attributes)

    def get_decoration(self):
        if not self.decoration:
            self.decoration = decoration()
            index = self.first_child_not_matching_class(Titular)
            if index is None:
                self.append(self.decoration)
            else:
                self.insert(index, self.decoration)
        return self.decoration


# ================
#  Title Elements
# ================

class title(Titular, PreBibliographic, TextElement): pass
class subtitle(Titular, PreBibliographic, TextElement): pass
class rubric(Titular, TextElement): pass


# ========================
#  Bibliographic Elements
# ========================

class docinfo(Bibliographic, Element): pass
class author(Bibliographic, TextElement): pass
class authors(Bibliographic, Element): pass
class organization(Bibliographic, TextElement): pass
class address(Bibliographic, FixedTextElement): pass
class contact(Bibliographic, TextElement): pass
class version(Bibliographic, TextElement): pass
class revision(Bibliographic, TextElement): pass
class status(Bibliographic, TextElement): pass
class date(Bibliographic, TextElement): pass
class copyright(Bibliographic, TextElement): pass


# =====================
#  Decorative Elements
# =====================

class decoration(Decorative, Element):

    def get_header(self):
        if not len(self.children) or not isinstance(self.children[0], header):
            self.insert(0, header())
        return self.children[0]

    def get_footer(self):
        if not len(self.children) or not isinstance(self.children[-1], footer):
            self.append(footer())
        return self.children[-1]


class header(Decorative, Element): pass
class footer(Decorative, Element): pass


# =====================
#  Structural Elements
# =====================

class section(Structural, Element): pass


class topic(Structural, Element):

    """
    Topics are terminal, "leaf" mini-sections, like block quotes with titles,
    or textual figures.  A topic is just like a section, except that it has no
    subsections, and it doesn't have to conform to section placement rules.

    Topics are allowed wherever body elements (list, table, etc.) are allowed,
    but only at the top level of a section or document.  Topics cannot nest
    inside topics, sidebars, or body elements; you can't have a topic inside a
    table, list, block quote, etc.
    """


class sidebar(Structural, Element):

    """
    Sidebars are like miniature, parallel documents that occur inside other
    documents, providing related or reference material.  A sidebar is
    typically offset by a border and "floats" to the side of the page; the
    document's main text may flow around it.  Sidebars can also be likened to
    super-footnotes; their content is outside of the flow of the document's
    main text.

    Sidebars are allowed wherever body elements (list, table, etc.) are
    allowed, but only at the top level of a section or document.  Sidebars
    cannot nest inside sidebars, topics, or body elements; you can't have a
    sidebar inside a table, list, block quote, etc.
    """


class transition(Structural, Element): pass


# ===============
#  Body Elements
# ===============

class paragraph(General, TextElement): pass
class compound(General, Element): pass
class bullet_list(Sequential, Element): pass
class enumerated_list(Sequential, Element): pass
class list_item(Part, Element): pass
class definition_list(Sequential, Element): pass
class definition_list_item(Part, Element): pass
class term(Part, TextElement): pass
class classifier(Part, TextElement): pass
class definition(Part, Element): pass
class field_list(Sequential, Element): pass
class field(Part, Element): pass
class field_name(Part, TextElement): pass
class field_body(Part, Element): pass


class option(Part, Element):

    child_text_separator = ''


class option_argument(Part, TextElement):

    def astext(self):
        return self.get('delimiter', ' ') + TextElement.astext(self)


class option_group(Part, Element):

    child_text_separator = ', '


class option_list(Sequential, Element): pass


class option_list_item(Part, Element):

    child_text_separator = '  '


class option_string(Part, TextElement): pass
class description(Part, Element): pass
class literal_block(General, FixedTextElement): pass
class doctest_block(General, FixedTextElement): pass
class line_block(General, Element): pass


class line(Part, TextElement):

    indent = None


class block_quote(General, Element): pass
class attribution(Part, TextElement): pass
class attention(Admonition, Element): pass
class caution(Admonition, Element): pass
class danger(Admonition, Element): pass
class error(Admonition, Element): pass
class important(Admonition, Element): pass
class note(Admonition, Element): pass
class tip(Admonition, Element): pass
class hint(Admonition, Element): pass
class warning(Admonition, Element): pass
class admonition(Admonition, Element): pass
class comment(Special, Invisible, FixedTextElement): pass
class substitution_definition(Special, Invisible, TextElement): pass
class target(Special, Invisible, Inline, TextElement, Targetable): pass
class footnote(General, BackLinkable, Element, Labeled, Targetable): pass
class citation(General, BackLinkable, Element, Labeled, Targetable): pass
class label(Part, TextElement): pass
class figure(General, Element): pass
class caption(Part, TextElement): pass
class legend(Part, Element): pass
class table(General, Element): pass
class tgroup(Part, Element): pass
class colspec(Part, Element): pass
class thead(Part, Element): pass
class tbody(Part, Element): pass
class row(Part, Element): pass
class entry(Part, Element): pass


class system_message(Special, BackLinkable, PreBibliographic, Element):

    def __init__(self, message=None, *children, **attributes):
        if message:
            p = paragraph('', message)
            children = (p,) + children
        try:
            Element.__init__(self, '', *children, **attributes)
        except:
            print 'system_message: children=%r' % (children,)
            raise

    def astext(self):
        line = self.get('line', '')
        return u'%s:%s: (%s/%s) %s' % (self['source'], line, self['type'],
                                       self['level'], Element.astext(self))


class pending(Special, Invisible, Element):

    """
    The "pending" element is used to encapsulate a pending operation: the
    operation (transform), the point at which to apply it, and any data it
    requires.  Only the pending operation's location within the document is
    stored in the public document tree (by the "pending" object itself); the
    operation and its data are stored in the "pending" object's internal
    instance attributes.

    For example, say you want a table of contents in your reStructuredText
    document.  The easiest way to specify where to put it is from within the
    document, with a directive::

        .. contents::

    But the "contents" directive can't do its work until the entire document
    has been parsed and possibly transformed to some extent.  So the directive
    code leaves a placeholder behind that will trigger the second phase of its
    processing, something like this::

         + internal attributes

    Use `document.note_pending()` so that the
    `docutils.transforms.Transformer` stage of processing can run all pending
    transforms.
    """

    def __init__(self, transform, details=None,
                 rawsource='', *children, **attributes):
        Element.__init__(self, rawsource, *children, **attributes)

        self.transform = transform
        """The `docutils.transforms.Transform` class implementing the pending
        operation."""

        self.details = details or {}
        """Detail data (dictionary) required by the pending operation."""

    def pformat(self, indent='    ', level=0):
        internals = [
              '.. internal attributes:',
              '     .transform: %s.%s' % (self.transform.__module__,
                                          self.transform.__name__),
              '     .details:']
        details = self.details.items()
        details.sort()
        for key, value in details:
            if isinstance(value, Node):
                internals.append('%7s%s:' % ('', key))
                internals.extend(['%9s%s' % ('', line)
                                  for line in value.pformat().splitlines()])
            elif value and isinstance(value, ListType) \
                  and isinstance(value[0], Node):
                internals.append('%7s%s:' % ('', key))
                for v in value:
                    internals.extend(['%9s%s' % ('', line)
                                      for line in v.pformat().splitlines()])
            else:
                internals.append('%7s%s: %r' % ('', key, value))
        return (Element.pformat(self, indent, level)
                + ''.join([('    %s%s\n' % (indent * level, line))
                           for line in internals]))

    def copy(self):
        return self.__class__(self.transform, self.details, self.rawsource,
                              **self.attributes)


class raw(Special, Inline, PreBibliographic, FixedTextElement):

    """
    Raw data that is to be passed untouched to the Writer.
    """

    pass


# =================
#  Inline Elements
# =================

class emphasis(Inline, TextElement): pass
class strong(Inline, TextElement): pass
class literal(Inline, TextElement): pass
class reference(General, Inline, Referential, TextElement): pass
class footnote_reference(Inline, Referential, TextElement): pass
class citation_reference(Inline, Referential, TextElement): pass
class substitution_reference(Inline, TextElement): pass
class title_reference(Inline, TextElement): pass
class abbreviation(Inline, TextElement): pass
class acronym(Inline, TextElement): pass
class superscript(Inline, TextElement): pass
class subscript(Inline, TextElement): pass


class image(General, Inline, Element):

    def astext(self):
        return self.get('alt', '')


class inline(Inline, TextElement): pass
class problematic(Inline, TextElement): pass
class generated(Inline, TextElement): pass


# ========================================
#  Auxiliary Classes, Functions, and Data
# ========================================

node_class_names = """
    Text
    abbreviation acronym address admonition attention attribution author
        authors
    block_quote bullet_list
    caption caution citation citation_reference classifier colspec comment
        compound contact copyright
    danger date decoration definition definition_list definition_list_item
        description docinfo doctest_block document
    emphasis entry enumerated_list error
    field field_body field_list field_name figure footer
        footnote footnote_reference
    generated
    header hint
    image important inline
    label legend line line_block list_item literal literal_block
    note
    option option_argument option_group option_list option_list_item
        option_string organization
    paragraph pending problematic
    raw reference revision row rubric
    section sidebar status strong subscript substitution_definition
        substitution_reference subtitle superscript system_message
    table target tbody term tgroup thead tip title title_reference topic
        transition
    version
    warning""".split()
"""A list of names of all concrete Node subclasses."""


class NodeVisitor:

    """
    "Visitor" pattern [GoF95]_ abstract superclass implementation for
    document tree traversals.

    Each node class has corresponding methods, doing nothing by
    default; override individual methods for specific and useful
    behaviour.  The `dispatch_visit()` method is called by
    `Node.walk()` upon entering a node.  `Node.walkabout()` also calls
    the `dispatch_departure()` method before exiting a node.

    The dispatch methods call "``visit_`` + node class name" or
    "``depart_`` + node class name", resp.

    This is a base class for visitors whose ``visit_...`` & ``depart_...``
    methods should be implemented for *all* node types encountered (such as
    for `docutils.writers.Writer` subclasses).  Unimplemented methods will
    raise exceptions.

    For sparse traversals, where only certain node types are of interest,
    subclass `SparseNodeVisitor` instead.  When (mostly or entirely) uniform
    processing is desired, subclass `GenericNodeVisitor`.

    .. [GoF95] Gamma, Helm, Johnson, Vlissides. *Design Patterns: Elements of
       Reusable Object-Oriented Software*. Addison-Wesley, Reading, MA, USA,
       1995.
    """

    optional = ()
    """
    Tuple containing node class names (as strings).

    No exception will be raised if writers do not implement visit
    or departure functions for these node classes.

    Used to ensure transitional compatibility with existing 3rd-party writers.
    """

    def __init__(self, document):
        self.document = document

    def dispatch_visit(self, node):
        """
        Call self."``visit_`` + node class name" with `node` as
        parameter.  If the ``visit_...`` method does not exist, call
        self.unknown_visit.
        """
        node_name = node.__class__.__name__
        method = getattr(self, 'visit_' + node_name, self.unknown_visit)
        self.document.reporter.debug(
            'docutils.nodes.NodeVisitor.dispatch_visit calling %s for %s'
            % (method.__name__, node_name))
        return method(node)

    def dispatch_departure(self, node):
        """
        Call self."``depart_`` + node class name" with `node` as
        parameter.  If the ``depart_...`` method does not exist, call
        self.unknown_departure.
        """
        node_name = node.__class__.__name__
        method = getattr(self, 'depart_' + node_name, self.unknown_departure)
        self.document.reporter.debug(
            'docutils.nodes.NodeVisitor.dispatch_departure calling %s for %s'
            % (method.__name__, node_name))
        return method(node)

    def unknown_visit(self, node):
        """
        Called when entering unknown `Node` types.

        Raise an exception unless overridden.
        """
        if  (node.document.settings.strict_visitor
             or node.__class__.__name__ not in self.optional):
            raise NotImplementedError(
                '%s visiting unknown node type: %s'
                % (self.__class__, node.__class__.__name__))

    def unknown_departure(self, node):
        """
        Called before exiting unknown `Node` types.

        Raise exception unless overridden.
        """
        if  (node.document.settings.strict_visitor
             or node.__class__.__name__ not in self.optional):
            raise NotImplementedError(
                '%s departing unknown node type: %s'
                % (self.__class__, node.__class__.__name__))


class SparseNodeVisitor(NodeVisitor):

    """
    Base class for sparse traversals, where only certain node types are of
    interest.  When ``visit_...`` & ``depart_...`` methods should be
    implemented for *all* node types (such as for `docutils.writers.Writer`
    subclasses), subclass `NodeVisitor` instead.
    """


class GenericNodeVisitor(NodeVisitor):

    """
    Generic "Visitor" abstract superclass, for simple traversals.

    Unless overridden, each ``visit_...`` method calls `default_visit()`, and
    each ``depart_...`` method (when using `Node.walkabout()`) calls
    `default_departure()`. `default_visit()` (and `default_departure()`) must
    be overridden in subclasses.

    Define fully generic visitors by overriding `default_visit()` (and
    `default_departure()`) only. Define semi-generic visitors by overriding
    individual ``visit_...()`` (and ``depart_...()``) methods also.

    `NodeVisitor.unknown_visit()` (`NodeVisitor.unknown_departure()`) should
    be overridden for default behavior.
    """

    def default_visit(self, node):
        """Override for generic, uniform traversals."""
        raise NotImplementedError

    def default_departure(self, node):
        """Override for generic, uniform traversals."""
        raise NotImplementedError

def _call_default_visit(self, node):
    self.default_visit(node)

def _call_default_departure(self, node):
    self.default_departure(node)

def _nop(self, node):
    pass

def _add_node_class_names(names):
    """Save typing with dynamic assignments:"""
    for _name in names:
        setattr(GenericNodeVisitor, "visit_" + _name, _call_default_visit)
        setattr(GenericNodeVisitor, "depart_" + _name, _call_default_departure)
        setattr(SparseNodeVisitor, 'visit_' + _name, _nop)
        setattr(SparseNodeVisitor, 'depart_' + _name, _nop)

_add_node_class_names(node_class_names)


class TreeCopyVisitor(GenericNodeVisitor):

    """
    Make a complete copy of a tree or branch, including element attributes.
    """

    def __init__(self, document):
        GenericNodeVisitor.__init__(self, document)
        self.parent_stack = []
        self.parent = []

    def get_tree_copy(self):
        return self.parent[0]

    def default_visit(self, node):
        """Copy the current node, and make it the new acting parent."""
        newnode = node.copy()
        self.parent.append(newnode)
        self.parent_stack.append(self.parent)
        self.parent = newnode

    def default_departure(self, node):
        """Restore the previous acting parent."""
        self.parent = self.parent_stack.pop()


class TreePruningException(Exception):

    """
    Base class for `NodeVisitor`-related tree pruning exceptions.

    Raise subclasses from within ``visit_...`` or ``depart_...`` methods
    called from `Node.walk()` and `Node.walkabout()` tree traversals to prune
    the tree traversed.
    """

    pass


class SkipChildren(TreePruningException):

    """
    Do not visit any children of the current node.  The current node's
    siblings and ``depart_...`` method are not affected.
    """

    pass


class SkipSiblings(TreePruningException):

    """
    Do not visit any more siblings (to the right) of the current node.  The
    current node's children and its ``depart_...`` method are not affected.
    """

    pass


class SkipNode(TreePruningException):

    """
    Do not visit the current node's children, and do not call the current
    node's ``depart_...`` method.
    """

    pass


class SkipDeparture(TreePruningException):

    """
    Do not call the current node's ``depart_...`` method.  The current node's
    children and siblings are not affected.
    """

    pass


class NodeFound(TreePruningException):

    """
    Raise to indicate that the target of a search has been found.  This
    exception must be caught by the client; it is not caught by the traversal
    code.
    """

    pass


def make_id(string):
    """
    Convert `string` into an identifier and return it.

    Docutils identifiers will conform to the regular expression
    ``[a-z](-?[a-z0-9]+)*``.  For CSS compatibility, identifiers (the "class"
    and "id" attributes) should have no underscores, colons, or periods.
    Hyphens may be used.

    - The `HTML 4.01 spec`_ defines identifiers based on SGML tokens:

          ID and NAME tokens must begin with a letter ([A-Za-z]) and may be
          followed by any number of letters, digits ([0-9]), hyphens ("-"),
          underscores ("_"), colons (":"), and periods (".").

    - However the `CSS1 spec`_ defines identifiers based on the "name" token,
      a tighter interpretation ("flex" tokenizer notation; "latin1" and
      "escape" 8-bit characters have been replaced with entities)::

          unicode     \\[0-9a-f]{1,4}
          latin1      [¡-ÿ]
          escape      {unicode}|\\[ -~¡-ÿ]
          nmchar      [-a-z0-9]|{latin1}|{escape}
          name        {nmchar}+

    The CSS1 "nmchar" rule does not include underscores ("_"), colons (":"),
    or periods ("."), therefore "class" and "id" attributes should not contain
    these characters. They should be replaced with hyphens ("-"). Combined
    with HTML's requirements (the first character must be a letter; no
    "unicode", "latin1", or "escape" characters), this results in the
    ``[a-z](-?[a-z0-9]+)*`` pattern.

    .. _HTML 4.01 spec: http://www.w3.org/TR/html401
    .. _CSS1 spec: http://www.w3.org/TR/REC-CSS1
    """
    id = _non_id_chars.sub('-', ' '.join(string.lower().split()))
    id = _non_id_at_ends.sub('', id)
    return str(id)

_non_id_chars = re.compile('[^a-z0-9]+')
_non_id_at_ends = re.compile('^[-0-9]+|-+$')

def dupname(node, name):
    node['dupnames'].append(name)
    node['names'].remove(name)
    # Assume that this method is referenced, even though it isn't; we
    # don't want to throw unnecessary system_messages.
    node.referenced = 1

def fully_normalize_name(name):
    """Return a case- and whitespace-normalized name."""
    return ' '.join(name.lower().split())

def whitespace_normalize_name(name):
    """Return a whitespace-normalized name."""
    return ' '.join(name.split())
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/0000755000175000017500000000000010447233610022555 5ustar  tseavertseaverZope-2.9.4-retire_zpkg/lib/python/docutils/languages/__init__.py0000644000175000017500000000126210322224711024661 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# Internationalization details are documented in
# .

"""
This package contains modules for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

_languages = {}

def get_language(language_code):
    if _languages.has_key(language_code):
        return _languages[language_code]
    module = __import__(language_code, globals(), locals())
    _languages[language_code] = module
    return module
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/sv.py0000644000175000017500000000412710322224711023555 0ustar  tseavertseaver# Author:    Adam Chodorowski
# Contact:   chodorowski@users.sourceforge.net
# Revision:  $Revision: 2224 $
# Date:      $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Swedish language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
    'author':       u'F\u00f6rfattare',
    'authors':      u'F\u00f6rfattare',
    'organization': u'Organisation',
    'address':      u'Adress',
    'contact':      u'Kontakt',
    'version':      u'Version',
    'revision':     u'Revision',
    'status':       u'Status',
    'date':         u'Datum',
    'copyright':    u'Copyright',
    'dedication':   u'Dedikation',
    'abstract':     u'Sammanfattning',
    'attention':    u'Observera!',
    'caution':      u'Varning!',
    'danger':       u'FARA!',
    'error':        u'Fel',
    'hint':         u'V\u00e4gledning',
    'important':    u'Viktigt',
    'note':         u'Notera',
    'tip':          u'Tips',
    'warning':      u'Varning',
    'contents':     u'Inneh\u00e5ll' }
"""Mapping of node class name to label text."""

bibliographic_fields = {
    # 'Author' and 'Authors' identical in Swedish; assume the plural:
    u'f\u00f6rfattare': 'authors',
    u' n/a':            'author',
    u'organisation':    'organization',
    u'adress':          'address',
    u'kontakt':         'contact',
    u'version':         'version',
    u'revision':        'revision',
    u'status':          'status',
    u'datum':           'date',
    u'copyright':       'copyright',
    u'dedikation':      'dedication', 
    u'sammanfattning':  'abstract' }
"""Swedish (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/de.py0000644000175000017500000000342510322224711023515 0ustar  tseavertseaver# Authors:   David Goodger; Gunnar Schwant
# Contact:   goodger@users.sourceforge.net
# Revision:  $Revision: 2224 $
# Date:      $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
German language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
    'author': 'Autor',
    'authors': 'Autoren',
    'organization': 'Organisation',
    'address': 'Adresse',
    'contact': 'Kontakt',
    'version': 'Version',
    'revision': 'Revision',
    'status': 'Status',
    'date': 'Datum',
    'dedication': 'Widmung',
    'copyright': 'Copyright',
    'abstract': 'Zusammenfassung',
    'attention': 'Achtung!',
    'caution': 'Vorsicht!',
    'danger': '!GEFAHR!',
    'error': 'Fehler',
    'hint': 'Hinweis',
    'important': 'Wichtig',
    'note': 'Bemerkung',
    'tip': 'Tipp',
    'warning': 'Warnung',
    'contents': 'Inhalt'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
    'autor': 'author',
    'autoren': 'authors',
    'organisation': 'organization',
    'adresse': 'address',
    'kontakt': 'contact',
    'version': 'version',
    'revision': 'revision',
    'status': 'status',
    'datum': 'date',
    'copyright': 'copyright',
    'widmung': 'dedication',
    'zusammenfassung': 'abstract'}
"""German (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/zh_tw.py0000644000175000017500000000456710322224711024270 0ustar  tseavertseaver# Author: Joe YS Jaw
# Contact: joeysj@users.sourceforge.net
# Revision: $Revision: 2608 $
# Date: $Date: 2004-09-13 21:09:56 +0200 (Mon, 13 Sep 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Traditional Chinese language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      'author': u'\u4f5c\u8005', # 'Author',
      'authors': u'\u4f5c\u8005\u7fa4', # 'Authors',
      'organization': u'\u7d44\u7e54', # 'Organization',
      'address': u'\u5730\u5740', # 'Address',
      'contact': u'\u9023\u7d61', # 'Contact',
      'version': u'\u7248\u672c', # 'Version',
      'revision': u'\u4fee\u8a02', # 'Revision',
      'status': u'\u72c0\u614b', # 'Status',
      'date': u'\u65e5\u671f', # 'Date',
      'copyright': u'\u7248\u6b0a', # 'Copyright',
      'dedication': u'\u984c\u737b', # 'Dedication',
      'abstract': u'\u6458\u8981', # 'Abstract',
      'attention': u'\u6ce8\u610f\uff01', # 'Attention!',
      'caution': u'\u5c0f\u5fc3\uff01', # 'Caution!',
      'danger': u'\uff01\u5371\u96aa\uff01', # '!DANGER!',
      'error': u'\u932f\u8aa4', # 'Error',
      'hint': u'\u63d0\u793a', # 'Hint',
      'important': u'\u91cd\u8981', # 'Important',
      'note': u'\u8a3b\u89e3', # 'Note',
      'tip': u'\u79d8\u8a23', # 'Tip',
      'warning': u'\u8b66\u544a', # 'Warning',
      'contents': u'\u76ee\u9304' # 'Contents'
} 
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      'author': 'author',
      'authors': 'authors',
      'organization': 'organization',
      'address': 'address',
      'contact': 'contact',
      'version': 'version',
      'revision': 'revision',
      'status': 'status',
      'date': 'date',
      'copyright': 'copyright',
      'dedication': 'dedication',
      'abstract': 'abstract'}
"""Traditional Chinese to canonical name mapping for bibliographic fields."""

author_separators = [u'\uff1b', u'\uff0c', u'\u3001',
                     ';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/fi.py0000644000175000017500000000403610322224711023522 0ustar  tseavertseaver# Author: Asko Soukka
# Contact: asko.soukka@iki.fi
# Revision: $Revision: 2609 $
# Date: $Date: 2004-09-13 21:25:33 +0200 (Mon, 13 Sep 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Finnish-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      u'author': u'Tekij\u00e4',
      u'authors': u'Tekij\u00e4t',
      u'organization': u'Yhteis\u00f6',
      u'address': u'Osoite',
      u'contact': u'Yhteystiedot',
      u'version': u'Versio',
      u'revision': u'Vedos',
      u'status': u'Tila',
      u'date': u'P\u00e4iv\u00e4ys',
      u'copyright': u'Tekij\u00e4noikeudet',
      u'dedication': u'Omistuskirjoitus',
      u'abstract': u'Tiivistelm\u00e4',
      u'attention': u'Huomio!',
      u'caution': u'Varo!',
      u'danger': u'!VAARA!',
      u'error': u'Virhe',
      u'hint': u'Vihje',
      u'important': u'T\u00e4rke\u00e4\u00e4',
      u'note': u'Huomautus',
      u'tip': u'Neuvo',
      u'warning': u'Varoitus',
      u'contents': u'Sis\u00e4llys'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      u'tekij\u00e4': u'author',
      u'tekij\u00e4t': u'authors',
      u'yhteis\u00f6': u'organization',
      u'osoite': u'address',
      u'yhteystiedot': u'contact',
      u'versio': u'version',
      u'vedos': u'revision',
      u'tila': u'status',
      u'p\u00e4iv\u00e4ys': u'date',
      u'tekij\u00e4noikeudet': u'copyright',
      u'omistuskirjoitus': u'dedication',
      u'tiivistelm\u00e4': u'abstract'}
"""Finnish (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/en.py0000644000175000017500000000356710322224711023536 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
English-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      'author': 'Author',
      'authors': 'Authors',
      'organization': 'Organization',
      'address': 'Address',
      'contact': 'Contact',
      'version': 'Version',
      'revision': 'Revision',
      'status': 'Status',
      'date': 'Date',
      'copyright': 'Copyright',
      'dedication': 'Dedication',
      'abstract': 'Abstract',
      'attention': 'Attention!',
      'caution': 'Caution!',
      'danger': '!DANGER!',
      'error': 'Error',
      'hint': 'Hint',
      'important': 'Important',
      'note': 'Note',
      'tip': 'Tip',
      'warning': 'Warning',
      'contents': 'Contents'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      'author': 'author',
      'authors': 'authors',
      'organization': 'organization',
      'address': 'address',
      'contact': 'contact',
      'version': 'version',
      'revision': 'revision',
      'status': 'status',
      'date': 'date',
      'copyright': 'copyright',
      'dedication': 'dedication',
      'abstract': 'abstract'}
"""English (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/eo.py0000644000175000017500000000372010322224711023526 0ustar  tseavertseaver# Author: Marcelo Huerta San Martin
# Contact: richieadler@users.sourceforge.net
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Esperanto-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      'author': u'A\u016dtoro',
      'authors': u'A\u016dtoroj',
      'organization': u'Organizo',
      'address': u'Adreso',
      'contact': u'Kontakto',
      'version': u'Versio',
      'revision': u'Revido',
      'status': u'Stato',
      'date': u'Dato',
      # 'copyright': u'Kopirajto',
      'copyright': u'A\u016dtorrajto',
      'dedication': u'Dedi\u0109o',
      'abstract': u'Resumo',
      'attention': u'Atentu!',
      'caution': u'Zorgu!',
      'danger': u'DAN\u011cERO!',
      'error': u'Eraro',
      'hint': u'Spuro',
      'important': u'Grava',
      'note': u'Noto',
      'tip': u'Helpeto',
      'warning': u'Averto',
      'contents': u'Enhavo'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      'a\u016dtoro': 'author',
      'a\u016dtoroj': 'authors',
      'organizo': 'organization',
      'adreso': 'address',
      'kontakto': 'contact',
      'versio': 'version',
      'revido': 'revision',
      'stato': 'status',
      'dato': 'date',
      'a\u016dtorrajto': 'copyright',
      'dedi\u0109o': 'dedication',
      'resumo': 'abstract'}
"""Esperanto (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/cs.py0000644000175000017500000000367410322224711023540 0ustar  tseavertseaver# Author: Marek Blaha
# Contact: mb@dat.cz
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Czech-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      'author': u'Autor',
      'authors': u'Auto\u0159i',
      'organization': u'Organizace',
      'address': u'Adresa',
      'contact': u'Kontakt',
      'version': u'Verze',
      'revision': u'Revize',
      'status': u'Stav',
      'date': u'Datum',
      'copyright': u'Copyright',
      'dedication': u'V\u011Bnov\u00E1n\u00ED',
      'abstract': u'Abstrakt',
      'attention': u'Pozor!',
      'caution': u'Opatrn\u011B!',
      'danger': u'!NEBEZPE\u010C\u00CD!',
      'error': u'Chyba',
      'hint': u'Rada',
      'important': u'D\u016Fle\u017Eit\u00E9',
      'note': u'Pozn\u00E1mka',
      'tip': u'Tip',
      'warning': u'Varov\u00E1n\u00ED',
      'contents': u'Obsah'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      u'autor': 'author',
      u'auto\u0159i': 'authors',
      u'organizace': 'organization',
      u'adresa': 'address',
      u'kontakt': 'contact',
      u'verze': 'version',
      u'revize': 'revision',
      u'stav': 'status',
      u'datum': 'date',
      u'copyright': 'copyright',
      u'v\u011Bnov\u00E1n\u00ED': 'dedication',
      u'abstrakt': 'abstract'}
"""Czech (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/pt_br.py0000644000175000017500000000377310322224711024241 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 2333 $
# Date: $Date: 2004-06-20 22:51:22 +0200 (Sun, 20 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Brazilian Portuguese-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      'author': u'Autor',
      'authors': u'Autores',
      'organization': u'Organiza\u00E7\u00E3o',
      'address': u'Endere\u00E7o',
      'contact': u'Contato',
      'version': u'Vers\u00E3o',
      'revision': u'Revis\u00E3o',
      'status': u'Estado',
      'date': u'Data',
      'copyright': u'Copyright',
      'dedication': u'Dedicat\u00F3ria',
      'abstract': u'Resumo',
      'attention': u'Atten\u00E7\u00E3o!',
      'caution': u'Cuidado!',
      'danger': u'PERIGO!',
      'error': u'Erro',
      'hint': u'Sugest\u00E3o',
      'important': u'Importante',
      'note': u'Nota',
      'tip': u'Dica',
      'warning': u'Aviso',
      'contents': u'Sum\u00E1rio'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      u'autor': 'author',
      u'autores': 'authors',
      u'organiza\u00E7\u00E3o': 'organization',
      u'endere\u00E7o': 'address',
      u'contato': 'contact',
      u'vers\u00E3o': 'version',
      u'revis\u00E3o': 'revision',
      u'estado': 'status',
      u'data': 'date',
      u'copyright': 'copyright',
      u'dedicat\u00F3ria': 'dedication',
      u'resumo': 'abstract'}
"""Brazilian Portuguese (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/fr.py0000644000175000017500000000363110322224711023533 0ustar  tseavertseaver# Author: Stefane Fermigier
# Contact: sf@fermigier.com
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
French-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      u'author': u'Auteur',
      u'authors': u'Auteurs',
      u'organization': u'Organisation',
      u'address': u'Adresse',
      u'contact': u'Contact',
      u'version': u'Version',
      u'revision': u'R\u00e9vision',
      u'status': u'Statut',
      u'date': u'Date',
      u'copyright': u'Copyright',
      u'dedication': u'D\u00e9dicace',
      u'abstract': u'R\u00e9sum\u00e9',
      u'attention': u'Attention!',
      u'caution': u'Avertissement!',
      u'danger': u'!DANGER!',
      u'error': u'Erreur',
      u'hint': u'Indication',
      u'important': u'Important',
      u'note': u'Note',
      u'tip': u'Astuce',
      u'warning': u'Avis',
      u'contents': u'Sommaire'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      u'auteur': u'author',
      u'auteurs': u'authors',
      u'organisation': u'organization',
      u'adresse': u'address',
      u'contact': u'contact',
      u'version': u'version',
      u'r\u00e9vision': u'revision',
      u'statut': u'status',
      u'date': u'date',
      u'copyright': u'copyright',
      u'd\u00e9dicace': u'dedication',
      u'r\u00e9sum\u00e9': u'abstract'}
"""French (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/es.py0000644000175000017500000000371510322224711023536 0ustar  tseavertseaver# -*- coding: iso-8859-1 -*-
# Author: Marcelo Huerta San Martn
# Contact: mghsm@uol.com.ar
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Spanish-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      'author': u'Autor',
      'authors': u'Autores',
      'organization': u'Organizaci\u00f3n',
      'address': u'Direcci\u00f3n',
      'contact': u'Contacto',
      'version': u'Versi\u00f3n',
      'revision': u'Revisi\u00f3n',
      'status': u'Estado',
      'date': u'Fecha',
      'copyright': u'Copyright',
      'dedication': u'Dedicatoria',
      'abstract': u'Resumen',
      'attention': u'\u00a1Atenci\u00f3n!',
      'caution': u'\u00a1Precauci\u00f3n!',
      'danger': u'\u00a1PELIGRO!',
      'error': u'Error',
      'hint': u'Sugerencia',
      'important': u'Importante',
      'note': u'Nota',
      'tip': u'Consejo',
      'warning': u'Advertencia',
      'contents': u'Contenido'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      u'autor': 'author',
      u'autores': 'authors',
      u'organizaci\u00f3n': 'organization',
      u'direcci\u00f3n': 'address',
      u'contacto': 'contact',
      u'versi\u00f3n': 'version',
      u'revisi\u00f3n': 'revision',
      u'estado': 'status',
      u'fecha': 'date',
      u'copyright': 'copyright',
      u'dedicatoria': 'dedication',
      u'resumen': 'abstract'}
"""Spanish (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/nl.py0000644000175000017500000000357510322225023023541 0ustar  tseavertseaver# Author: Martijn Pieters
# Contact: mjpieters@users.sourceforge.net
# Revision: $Revision: 3058 $
# Date: $Date: 2005-03-18 21:09:22 +0100 (Fri, 18 Mar 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Dutch-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      'author': 'Auteur',
      'authors': 'Auteurs',
      'organization': 'Organisatie',
      'address': 'Adres',
      'contact': 'Contact',
      'version': 'Versie',
      'revision': 'Revisie',
      'status': 'Status',
      'date': 'Datum',
      'copyright': 'Copyright',
      'dedication': 'Toewijding',
      'abstract': 'Samenvatting',
      'attention': 'Attentie!',
      'caution': 'Let op!',
      'danger': '!GEVAAR!',
      'error': 'Fout',
      'hint': 'Hint',
      'important': 'Belangrijk',
      'note': 'Opmerking',
      'tip': 'Tip',
      'warning': 'Waarschuwing',
      'contents': 'Inhoud'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      'auteur': 'author',
      'auteurs': 'authors',
      'organisatie': 'organization',
      'adres': 'address',
      'contact': 'contact',
      'versie': 'version',
      'revisie': 'revision',
      'status': 'status',
      'datum': 'date',
      'copyright': 'copyright',
      'toewijding': 'dedication',
      'samenvatting': 'abstract'}
"""Dutch (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/it.py0000644000175000017500000000350410322224711023537 0ustar  tseavertseaver# Author: Nicola Larosa
# Contact: docutils@tekNico.net
# Revision: $Revision: 2944 $
# Date: $Date: 2005-01-20 13:11:50 +0100 (Thu, 20 Jan 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Italian-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      'author': 'Autore',
      'authors': 'Autori',
      'organization': 'Organizzazione',
      'address': 'Indirizzo',
      'contact': 'Contatti',
      'version': 'Versione',
      'revision': 'Revisione',
      'status': 'Status',
      'date': 'Data',
      'copyright': 'Copyright',
      'dedication': 'Dedica',
      'abstract': 'Riassunto',
      'attention': 'Attenzione!',
      'caution': 'Cautela!',
      'danger': '!PERICOLO!',
      'error': 'Errore',
      'hint': 'Suggerimento',
      'important': 'Importante',
      'note': 'Nota',
      'tip': 'Consiglio',
      'warning': 'Avvertenza',
      'contents': 'Indice'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      'autore': 'author',
      'autori': 'authors',
      'organizzazione': 'organization',
      'indirizzo': 'address',
      'contatto': 'contact',
      'versione': 'version',
      'revisione': 'revision',
      'status': 'status',
      'data': 'date',
      'copyright': 'copyright',
      'dedica': 'dedication',
      'riassunto': 'abstract'}
"""Italian (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/sk.py0000644000175000017500000000357510322224711023550 0ustar  tseavertseaver# :Author: Miroslav Vasko
# :Contact: zemiak@zoznam.sk
# :Revision: $Revision: 2224 $
# :Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# :Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Slovak-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      'author': u'Autor',
      'authors': u'Autori',
      'organization': u'Organiz\u00E1cia',
      'address': u'Adresa',
      'contact': u'Kontakt',
      'version': u'Verzia',
      'revision': u'Rev\u00EDzia',
      'status': u'Stav',
      'date': u'D\u00E1tum',
      'copyright': u'Copyright',
      'dedication': u'Venovanie',
      'abstract': u'Abstraktne',
      'attention': u'Pozor!',
      'caution': u'Opatrne!',
      'danger': u'!NEBEZPE\u010cENSTVO!',
      'error': u'Chyba',
      'hint': u'Rada',
      'important': u'D\u00F4le\u017Eit\u00E9',
      'note': u'Pozn\u00E1mka',
      'tip': u'Tip',
      'warning': u'Varovanie',
      'contents': u'Obsah'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      u'autor': 'author',
      u'autori': 'authors',
      u'organiz\u00E1cia': 'organization',
      u'adresa': 'address',
      u'kontakt': 'contact',
      u'verzia': 'version',
      u'rev\u00EDzia': 'revision',
      u'stav': 'status',
      u'd\u00E1tum': 'date',
      u'copyright': 'copyright',
      u'venovanie': 'dedication',
      u'abstraktne': 'abstract'}
"""Slovak (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/ca.py0000644000175000017500000000371010322225023023502 0ustar  tseavertseaver# Author: Ivan Vilata i Balaguer
# Contact: ivan@selidor.net
# Revision: $Revision: 3276 $
# Date: $Date: 2005-04-30 13:34:52 +0200 (Sat, 30 Apr 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Catalan-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      # fixed: language-dependent
      'author': u'Autor',
      'authors': u'Autors',
      'organization': u'Organitzaci\u00F3',
      'address': u'Adre\u00E7a',
      'contact': u'Contacte',
      'version': u'Versi\u00F3',
      'revision': u'Revisi\u00F3',
      'status': u'Estat',
      'date': u'Data',
      'copyright': u'Copyright',
      'dedication': u'Dedicat\u00F2ria',
      'abstract': u'Resum',
      'attention': u'Atenci\u00F3!',
      'caution': u'Compte!',
      'danger': u'PERILL!',
      'error': u'Error',
      'hint': u'Suggeriment',
      'important': u'Important',
      'note': u'Nota',
      'tip': u'Consell',
      'warning': u'Av\u00EDs',
      'contents': u'Contingut'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      # language-dependent: fixed
      u'autor': 'author',
      u'autors': 'authors',
      u'organitzaci\u00F3': 'organization',
      u'adre\u00E7a': 'address',
      u'contacte': 'contact',
      u'versi\u00F3': 'version',
      u'revisi\u00F3': 'revision',
      u'estat': 'status',
      u'data': 'date',
      u'copyright': 'copyright',
      u'dedicat\u00F2ria': 'dedication',
      u'resum': 'abstract'}
"""Catalan (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/ru.py0000644000175000017500000000636510322224711023561 0ustar  tseavertseaver# Author: Roman Suzi
# Contact: rnd@onego.ru
# Revision: $Revision: 2999 $
# Date: $Date: 2005-03-03 20:35:02 +0100 (Thu, 03 Mar 2005) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Russian-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      u'abstract': u'\u0410\u043d\u043d\u043e\u0442\u0430\u0446\u0438\u044f',
      u'address': u'\u0410\u0434\u0440\u0435\u0441',
      u'attention': u'\u0412\u043d\u0438\u043c\u0430\u043d\u0438\u0435!',
      u'author': u'\u0410\u0432\u0442\u043e\u0440',
      u'authors': u'\u0410\u0432\u0442\u043e\u0440\u044b',
      u'caution': u'\u041e\u0441\u0442\u043e\u0440\u043e\u0436\u043d\u043e!',
      u'contact': u'\u041a\u043e\u043d\u0442\u0430\u043a\u0442',
      u'contents':
      u'\u0421\u043e\u0434\u0435\u0440\u0436\u0430\u043d\u0438\u0435',
      u'copyright': u'\u041f\u0440\u0430\u0432\u0430 '
      u'\u043a\u043e\u043f\u0438\u0440\u043e\u0432\u0430\u043d\u0438\u044f',
      u'danger': u'\u041e\u041f\u0410\u0421\u041d\u041e!',
      u'date': u'\u0414\u0430\u0442\u0430',
      u'dedication':
      u'\u041f\u043e\u0441\u0432\u044f\u0449\u0435\u043d\u0438\u0435',
      u'error': u'\u041e\u0448\u0438\u0431\u043a\u0430',
      u'hint': u'\u0421\u043e\u0432\u0435\u0442',
      u'important': u'\u0412\u0430\u0436\u043d\u043e',
      u'note': u'\u041f\u0440\u0438\u043c\u0435\u0447\u0430\u043d\u0438\u0435',
      u'organization':
      u'\u041e\u0440\u0433\u0430\u043d\u0438\u0437\u0430\u0446\u0438\u044f',
      u'revision': u'\u0420\u0435\u0434\u0430\u043a\u0446\u0438\u044f',
      u'status': u'\u0421\u0442\u0430\u0442\u0443\u0441',
      u'tip': u'\u041f\u043e\u0434\u0441\u043a\u0430\u0437\u043a\u0430',
      u'version': u'\u0412\u0435\u0440\u0441\u0438\u044f',
      u'warning': u'\u041f\u0440\u0435\u0434\u0443\u043f\u0440\u0435\u0436'
      u'\u0434\u0435\u043d\u0438\u0435'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      u'\u0430\u043d\u043d\u043e\u0442\u0430\u0446\u0438\u044f': u'abstract',
      u'\u0430\u0434\u0440\u0435\u0441': u'address',
      u'\u0430\u0432\u0442\u043e\u0440': u'author',
      u'\u0430\u0432\u0442\u043e\u0440\u044b': u'authors',
      u'\u043a\u043e\u043d\u0442\u0430\u043a\u0442': u'contact',
      u'\u043f\u0440\u0430\u0432\u0430 \u043a\u043e\u043f\u0438\u0440\u043e'
      u'\u0432\u0430\u043d\u0438\u044f': u'copyright',
      u'\u0434\u0430\u0442\u0430': u'date',
      u'\u043f\u043e\u0441\u0432\u044f\u0449\u0435\u043d\u0438\u0435':
      u'dedication',
      u'\u043e\u0440\u0433\u0430\u043d\u0438\u0437\u0430\u0446\u0438\u044f':
      u'organization',
      u'\u0440\u0435\u0434\u0430\u043a\u0446\u0438\u044f': u'revision',
      u'\u0441\u0442\u0430\u0442\u0443\u0441': u'status',
      u'\u0432\u0435\u0440\u0441\u0438\u044f': u'version'}
"""Russian (lowcased) to canonical name mapping for bibliographic fields."""

author_separators =  [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/languages/af.py0000644000175000017500000000352410322224711023513 0ustar  tseavertseaver# Author: Jannie Hofmeyr
# Contact: jhsh@sun.ac.za
# Revision: $Revision: 2224 $
# Date: $Date: 2004-06-05 21:40:46 +0200 (Sat, 05 Jun 2004) $
# Copyright: This module has been placed in the public domain.

# New language mappings are welcome.  Before doing a new translation, please
# read .  Two files must be
# translated for each language: one in docutils/languages, the other in
# docutils/parsers/rst/languages.

"""
Afrikaans-language mappings for language-dependent features of Docutils.
"""

__docformat__ = 'reStructuredText'

labels = {
      'author': 'Auteur',
      'authors': 'Auteurs',
      'organization': 'Organisasie',
      'address': 'Adres',
      'contact': 'Kontak',
      'version': 'Weergawe',
      'revision': 'Revisie',
      'status': 'Status',
      'date': 'Datum',
      'copyright': 'Kopiereg',
      'dedication': 'Opdrag',
      'abstract': 'Opsomming',
      'attention': 'Aandag!',
      'caution': 'Wees versigtig!',
      'danger': '!GEVAAR!',
      'error': 'Fout',
      'hint': 'Wenk',
      'important': 'Belangrik',
      'note': 'Nota',
      'tip': 'Tip', # hint and tip both have the same translation: wenk
      'warning': 'Waarskuwing',
      'contents': 'Inhoud'}
"""Mapping of node class name to label text."""

bibliographic_fields = {
      'auteur': 'author',
      'auteurs': 'authors',
      'organisasie': 'organization',
      'adres': 'address',
      'kontak': 'contact',
      'weergawe': 'version',
      'revisie': 'revision',
      'status': 'status',
      'datum': 'date',
      'kopiereg': 'copyright',
      'opdrag': 'dedication',
      'opsomming': 'abstract'}
"""Afrikaans (lowcased) to canonical name mapping for bibliographic fields."""

author_separators = [';', ',']
"""List of separator strings for the 'Authors' bibliographic field. Tried in
order."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/examples.py0000644000175000017500000000750410322224711022777 0ustar  tseavertseaver# Authors: David Goodger
# Contact: goodger@python.org
# Revision: $Revision: 3247 $
# Date: $Date: 2005-04-23 21:23:57 +0200 (Sat, 23 Apr 2005) $
# Copyright: This module has been placed in the public domain.

"""
This module contains practical examples of Docutils client code.

Importing this module from client code is not recommended; its contents are
subject to change in future Docutils releases.  Instead, it is recommended
that you copy and paste the parts you need into your own code, modifying as
necessary.
"""

from docutils import core, io


def html_parts(input_string, source_path=None, destination_path=None,
               input_encoding='unicode', doctitle=1, initial_header_level=1):
    """
    Given an input string, returns a dictionary of HTML document parts.

    Dictionary keys are the names of parts, and values are Unicode strings;
    encoding is up to the client.

    Parameters:

    - `input_string`: A multi-line text string; required.
    - `source_path`: Path to the source file or object.  Optional, but useful
      for diagnostic output (system messages).
    - `destination_path`: Path to the file or object which will receive the
      output; optional.  Used for determining relative paths (stylesheets,
      source links, etc.).
    - `input_encoding`: The encoding of `input_string`.  If it is an encoded
      8-bit string, provide the correct encoding.  If it is a Unicode string,
      use "unicode", the default.
    - `doctitle`: Disable the promotion of a lone top-level section title to
      document title (and subsequent section title to document subtitle
      promotion); enabled by default.
    - `initial_header_level`: The initial level for header elements (e.g. 1
      for "
").
    """
    overrides = {'input_encoding': input_encoding,
                 'doctitle_xform': doctitle,
                 'initial_header_level': initial_header_level}
    parts = core.publish_parts(
        source=input_string, source_path=source_path,
        destination_path=destination_path,
        writer_name='html', settings_overrides=overrides)
    return parts

def html_fragment(input_string, source_path=None, destination_path=None,
                  input_encoding='unicode', output_encoding='unicode',
                  doctitle=1, initial_header_level=1):
    """
    Given an input string, returns an HTML fragment as a string.

    The return value is the contents of the  tag, less the title,
    subtitle, and docinfo.

    Parameters (see `html_parts()` for the remainder):

    - `output_encoding`: The desired encoding of the output.  If a Unicode
      string is desired, use the default value of "unicode" .
    """
    parts = html_parts(
        input_string=input_string, source_path=source_path,
        destination_path=destination_path,
        input_encoding=input_encoding, doctitle=doctitle,
        initial_header_level=initial_header_level)
    fragment = parts['fragment']
    if output_encoding != 'unicode':
        fragment = fragment.encode(output_encoding)
    return fragment

def internals(input_string, source_path=None, destination_path=None,
              input_encoding='unicode'):
    """
    Return the document tree and publisher, for exploring Docutils internals.

    Parameters: see `html_parts()`.
    """
    overrides = {'input_encoding': input_encoding}
    output, pub = core.publish_programmatically(
        source_class=io.StringInput, source=input_string,
        source_path=source_path,
        destination_class=io.NullOutput, destination=None,
        destination_path=destination_path,
        reader=None, reader_name='standalone',
        parser=None, parser_name='restructuredtext',
        writer=None, writer_name='null',
        settings=None, settings_spec=None, settings_overrides=overrides,
        config_section=None, enable_exit_status=None)
    return pub.writer.document, pub
Zope-2.9.4-retire_zpkg/lib/python/docutils/frontend.py0000644000175000017500000007437710322224711023014 0ustar  tseavertseaver# Author: David Goodger
# Contact: goodger@users.sourceforge.net
# Revision: $Revision: 3358 $
# Date: $Date: 2005-05-21 02:00:25 +0200 (Sat, 21 May 2005) $
# Copyright: This module has been placed in the public domain.

"""
Command-line and common processing for Docutils front-end tools.

Exports the following classes:

* `OptionParser`: Standard Docutils command-line processing.
* `Option`: Customized version of `optparse.Option`; validation support.
* `Values`: Runtime settings; objects are simple structs
  (``object.attribute``).  Supports cumulative list settings (attributes).
* `ConfigParser`: Standard Docutils config file processing.

Also exports the following functions:

* Option callbacks: `store_multiple`, `read_config_file`.
* Setting validators: `validate_encoding`,
  `validate_encoding_error_handler`,
  `validate_encoding_and_error_handler`, `validate_boolean`,
  `validate_threshold`, `validate_colon_separated_string_list`,
  `validate_dependency_file`.
* `make_paths_absolute`.
"""

__docformat__ = 'reStructuredText'

import os
import os.path
import sys
import types
import copy
import warnings
import ConfigParser as CP
import codecs
import docutils
import optparse
from optparse import SUPPRESS_HELP


def store_multiple(option, opt, value, parser, *args, **kwargs):
    """
    Store multiple values in `parser.values`.  (Option callback.)

    Store `None` for each attribute named in `args`, and store the value for
    each key (attribute name) in `kwargs`.
    """
    for attribute in args:
        setattr(parser.values, attribute, None)
    for key, value in kwargs.items():
        setattr(parser.values, key, value)

def read_config_file(option, opt, value, parser):
    """
    Read a configuration file during option processing.  (Option callback.)
    """
    try:
        new_settings = parser.get_config_file_settings(value)
    except ValueError, error:
        parser.error(error)
    parser.values.update(new_settings, parser)

def validate_encoding(setting, value, option_parser,
                      config_parser=None, config_section=None):
    try:
        codecs.lookup(value)
    except LookupError:
        raise (LookupError('setting "%s": unknown encoding: "%s"'
                           % (setting, value)),
               None, sys.exc_info()[2])
    return value

def validate_encoding_error_handler(setting, value, option_parser,
                                    config_parser=None, config_section=None):
    try:
        codecs.lookup_error(value)
    except AttributeError:              # prior to Python 2.3
        if value not in ('strict', 'ignore', 'replace', 'xmlcharrefreplace'):
            raise (LookupError(
                'unknown encoding error handler: "%s" (choices: '
                '"strict", "ignore", "replace", or "xmlcharrefreplace")' % value),
                   None, sys.exc_info()[2])
    except LookupError:
        raise (LookupError(
            'unknown encoding error handler: "%s" (choices: '
            '"strict", "ignore", "replace", "backslashreplace", '
            '"xmlcharrefreplace", and possibly others; see documentation for '
            'the Python ``codecs`` module)' % value),
               None, sys.exc_info()[2])
    return value

def validate_encoding_and_error_handler(
    setting, value, option_parser, config_parser=None, config_section=None):
    """
    Side-effect: if an error handler is included in the value, it is inserted
    into the appropriate place as if it was a separate setting/option.
    """
    if ':' in value:
        encoding, handler = value.split(':')
        validate_encoding_error_handler(
            setting + '_error_handler', handler, option_parser,
            config_parser, config_section)
        if config_parser:
            config_parser.set(config_section, setting + '_error_handler',
                              handler)
        else:
            setattr(option_parser.values, setting + '_error_handler', handler)
    else:
        encoding = value
    validate_encoding(setting, encoding, option_parser,
                      config_parser, config_section)
    return encoding

def validate_boolean(setting, value, option_parser,
                     config_parser=None, config_section=None):
    if isinstance(value, types.StringType):
        try:
            return option_parser.booleans[value.strip().lower()]
        except KeyError:
            raise (LookupError('unknown boolean value: "%s"' % value),
                   None, sys.exc_info()[2])
    return value

def validate_nonnegative_int(setting, value, option_parser,
                             config_parser=None, config_section=None):
    value = int(value)
    if value < 0:
        raise ValueError('negative value; must be positive or zero')
    return value

def validate_threshold(setting, value, option_parser,
                       config_parser=None, config_section=None):
    try:
        return int(value)
    except ValueError:
        try:
            return option_parser.thresholds[value.lower()]
        except (KeyError, AttributeError):
            raise (LookupError('unknown threshold: %r.' % value),
                   None, sys.exc_info[2])

def validate_colon_separated_string_list(
    setting, value, option_parser, config_parser=None, config_section=None):
    if isinstance(value, types.StringType):
        value = value.split(':')
    else:
        last = value.pop()
        value.extend(last.split(':'))
    return value

def validate_url_trailing_slash(
    setting, value, option_parser, config_parser=None, config_section=None):
    if not value:
        return './'
    elif value.endswith('/'):
        return value
    else:
        return value + '/'

def validate_dependency_file(
    setting, value, option_parser, config_parser=None, config_section=None):
    try:
        return docutils.utils.DependencyList(value)
    except IOError:
        return docutils.utils.DependencyList(None)

def make_paths_absolute(pathdict, keys, base_path=None):
    """
    Interpret filesystem path settings relative to the `base_path` given.

    Paths are values in `pathdict` whose keys are in `keys`.  Get `keys` from
    `OptionParser.relative_path_settings`.
    """
    if base_path is None:
        base_path = os.getcwd()
    for key in keys:
        if pathdict.has_key(key):
            value = pathdict[key]
            if isinstance(value, types.ListType):
                value = [make_one_path_absolute(base_path, path)
                         for path in value]
            elif value:
                value = make_one_path_absolute(base_path, value)
            pathdict[key] = value

def make_one_path_absolute(base_path, path):
    return os.path.abspath(os.path.join(base_path, path))


class Values(optparse.Values):

    """
    Updates list attributes by extension rather than by replacement.
    Works in conjunction with the `OptionParser.lists` instance attribute.
    """

    def __init__(self, *args, **kwargs):
        optparse.Values.__init__(self, *args, **kwargs)
        if (not hasattr(self, 'record_dependencies')
            or self.record_dependencies is None):
            # Set up dependency list, in case it is needed.
            self.record_dependencies = docutils.utils.DependencyList()

    def update(self, other_dict, option_parser):
        if isinstance(other_dict, Values):
            other_dict = other_dict.__dict__
        other_dict = other_dict.copy()
        for setting in option_parser.lists.keys():
            if (hasattr(self, setting) and other_dict.has_key(setting)):
                value = getattr(self, setting)
                if value:
                    value += other_dict[setting]
                    del other_dict[setting]
        self._update_loose(other_dict)


class Option(optparse.Option):

    ATTRS = optparse.Option.ATTRS + ['validator', 'overrides']

    def process(self, opt, value, values, parser):
        """
        Call the validator function on applicable settings and
        evaluate the 'overrides' option.
        Extends `optparse.Option.process`.
        """
        result = optparse.Option.process(self, opt, value, values, parser)
        setting = self.dest
        if setting:
            if self.validator:
                value = getattr(values, setting)
                try:
                    new_value = self.validator(setting, value, parser)
                except Exception, error:
                    raise (optparse.OptionValueError(
                        'Error in option "%s":\n    %s: %s'
                        % (opt, error.__class__.__name__, error)),
                           None, sys.exc_info()[2])
                setattr(values, setting, new_value)
            if self.overrides:
                setattr(values, self.overrides, None)
        return result


class OptionParser(optparse.OptionParser, docutils.SettingsSpec):

    """
    Parser for command-line and library use.  The `settings_spec`
    specification here and in other Docutils components are merged to build
    the set of command-line options and runtime settings for this process.

    Common settings (defined below) and component-specific settings must not
    conflict.  Short options are reserved for common settings, and components
    are restrict to using long options.
    """

    standard_config_files = [
        '/etc/docutils.conf',           # system-wide
        './docutils.conf',              # project-specific
        '~/.docutils']                  # user-specific
    """Docutils configuration files, using ConfigParser syntax.  Filenames
    will be tilde-expanded later.  Later files override earlier ones."""

    threshold_choices = 'info 1 warning 2 error 3 severe 4 none 5'.split()
    """Possible inputs for for --report and --halt threshold values."""

    thresholds = {'info': 1, 'warning': 2, 'error': 3, 'severe': 4, 'none': 5}
    """Lookup table for --report and --halt threshold values."""

    booleans={'1': 1, 'on': 1, 'yes': 1, 'true': 1,
              '0': 0, 'off': 0, 'no': 0, 'false': 0, '': 0}
    """Lookup table for boolean configuration file settings."""

    if hasattr(codecs, 'backslashreplace_errors'):
        default_error_encoding_error_handler = 'backslashreplace'
    else:
        default_error_encoding_error_handler = 'replace'

    settings_spec = (
        'General Docutils Options',
        None,
        (('Include a "Generated by Docutils" credit and link at the end '
          'of the document.',
          ['--generator', '-g'], {'action': 'store_true',
                                  'validator': validate_boolean}),
         ('Do not include a generator credit.',
          ['--no-generator'], {'action': 'store_false', 'dest': 'generator'}),
         ('Include the date at the end of the document (UTC).',
          ['--date', '-d'], {'action': 'store_const', 'const': '%Y-%m-%d',
                             'dest': 'datestamp'}),
         ('Include the time & date at the end of the document (UTC).',
          ['--time', '-t'], {'action': 'store_const',
                             'const': '%Y-%m-%d %H:%M UTC',
                             'dest': 'datestamp'}),
         ('Do not include a datestamp of any kind.',
          ['--no-datestamp'], {'action': 'store_const', 'const': None,
                               'dest': 'datestamp'}),
         ('Include a "View document source" link (relative to destination).',
          ['--source-link', '-s'], {'action': 'store_true',
                                    'validator': validate_boolean}),
         ('Use the supplied  verbatim for a "View document source" '
          'link; implies --source-link.',
          ['--source-url'], {'metavar': ''}),
         ('Do not include a "View document source" link.',
          ['--no-source-link'],
          {'action': 'callback', 'callback': store_multiple,
           'callback_args': ('source_link', 'source_url')}),
         ('Enable backlinks from section headers to table of contents '
          'entries.  This is the default.',
          ['--toc-entry-backlinks'],
          {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'entry',
           'default': 'entry'}),
         ('Enable backlinks from section headers to the top of the table of '
          'contents.',
          ['--toc-top-backlinks'],
          {'dest': 'toc_backlinks', 'action': 'store_const', 'const': 'top'}),
         ('Disable backlinks to the table of contents.',
          ['--no-toc-backlinks'],
          {'dest': 'toc_backlinks', 'action': 'store_false'}),
         ('Enable backlinks from footnotes and citations to their '
          'references.  This is the default.',
          ['--footnote-backlinks'],
          {'action': 'store_true', 'default': 1,
           'validator': validate_boolean}),
         ('Disable backlinks from footnotes and citations.',
          ['--no-footnote-backlinks'],
          {'dest': 'footnote_backlinks', 'action': 'store_false'}),
         ('Disable Docutils section numbering',
          ['--no-section-numbering'],
          {'action': 'store_false', 'dest': 'sectnum_xform',
           'default': 1, 'validator': validate_boolean}),
         ('Set verbosity threshold; report system messages at or higher than '
          ' (by name or number: "info" or "1", warning/2, error/3, '
          'severe/4; also, "none" or "5").  Default is 2 (warning).',
          ['--report', '-r'], {'choices': threshold_choices, 'default': 2,
                               'dest': 'report_level', 'metavar': '',
                               'validator': validate_threshold}),
         ('Report all system messages, info-level and higher.  (Same as '
          '"--report=info".)',
          ['--verbose', '-v'], {'action': 'store_const', 'const': 1,
                                'dest': 'report_level'}),
         ('Do not report any system messages.  (Same as "--report=none".)',
          ['--quiet', '-q'], {'action': 'store_const', 'const': 5,
                              'dest': 'report_level'}),
         ('Set the threshold () at or above which system messages are '
          'converted to exceptions, halting execution immediately by '
          'exiting (or propagating the exception if --traceback set).  '
          'Levels as in --report.  Default is 4 (severe).',
          ['--halt'], {'choices': threshold_choices, 'dest': 'halt_level',
                       'default': 4, 'metavar': '',
                       'validator': validate_threshold}),
         ('Same as "--halt=info": halt processing at the slightest problem.',
          ['--strict'], {'action': 'store_const', 'const': 'info',
                         'dest': 'halt_level'}),
         ('Enable a non-zero exit status for normal exit if non-halting '
          'system messages (at or above ) were generated.  Levels as '
          'in --report.  Default is 5 (disabled).  Exit status is the maximum '
          'system message level plus 10 (11 for INFO, etc.).',
          ['--exit-status'], {'choices': threshold_choices,
                              'dest': 'exit_status_level',
                              'default': 5, 'metavar': '',
                              'validator': validate_threshold}),
         ('Report debug-level system messages and generate diagnostic output.',
          ['--debug'], {'action': 'store_true', 'validator': validate_boolean}),
         ('Do not report debug-level system messages or generate diagnostic '
          'output.',
          ['--no-debug'], {'action': 'store_false', 'dest': 'debug'}),
         ('Send the output of system messages (warnings) to .',
          ['--warnings'], {'dest': 'warning_stream', 'metavar': ''}),
         ('Enable Python tracebacks when halt-level system messages and '
          'other exceptions occur.  Useful for debugging, and essential for '
          'issue reports.',
          ['--traceback'], {'action': 'store_true', 'default': None,
                            'validator': validate_boolean}),
         ('Disable Python tracebacks when errors occur; report just the error '
          'instead.  This is the default.',
          ['--no-traceback'], {'dest': 'traceback', 'action': 'store_false'}),
         ('Specify the encoding of input text.  Default is locale-dependent.  '
          'Optionally also specify the error handler for undecodable '
          'characters, after a colon (":"); default is "strict".  (See '
          '"--intput-encoding-error-handler".)',
          ['--input-encoding', '-i'],
          {'metavar': '',
           'validator': validate_encoding_and_error_handler}),
         ('Specify the error handler for undecodable characters in '
          'the input.  Acceptable values include "strict", "ignore", and '
          '"replace".  Default is "strict".  '
          'Usually specified as part of --input-encoding.',
          ['--input-encoding-error-handler'],
          {'default': 'strict', 'validator': validate_encoding_error_handler}),
         ('Specify the text encoding for output.  Default is UTF-8.  '
          'Optionally also specify the error handler for unencodable '
          'characters, after a colon (":"); default is "strict".  (See '
          '"--output-encoding-error-handler".)',
          ['--output-encoding', '-o'],
          {'metavar': '', 'default': 'utf-8',
           'validator': validate_encoding_and_error_handler}),
         ('Specify the error handler for unencodable characters in '
          'the output.  Acceptable values include "strict", "ignore", '
          '"replace", "xmlcharrefreplace", and '
          '"backslashreplace" (in Python 2.3+).  Default is "strict".  '
          'Usually specified as part of --output-encoding.',
          ['--output-encoding-error-handler'],
          {'default': 'strict', 'validator': validate_encoding_error_handler}),
         ('Specify the text encoding for error output.  Default is ASCII.  '
          'Optionally also specify the error handler for unencodable '
          'characters, after a colon (":"); default is "%s".  (See '
          '"--output-encoding-error-handler".)'
          % default_error_encoding_error_handler,
          ['--error-encoding', '-e'],
          {'metavar': '', 'default': 'ascii',
           'validator': validate_encoding_and_error_handler}),
         ('Specify the error handler for unencodable characters in '
          'error output.  See --output-encoding-error-handler for acceptable '
          'values.  Default is "%s".  Usually specified as part of '
          '--error-encoding.' % default_error_encoding_error_handler,
          ['--error-encoding-error-handler'],
          {'default': default_error_encoding_error_handler,
           'validator': validate_encoding_error_handler}),
         ('Specify the language of input text (ISO 639 2-letter identifier).'
          '  Default is "en" (English).',
          ['--language', '-l'], {'dest': 'language_code', 'default': 'en',
                                 'metavar': ''}),
         ('Write dependencies (caused e.g. by file inclusions) to '
          '.  Useful in conjunction with programs like "make".',
          ['--record-dependencies'],
          {'metavar': '', 'validator': validate_dependency_file,
           'default': None}),           # default set in Values class
         ('Read configuration settings from , if it exists.',
          ['--config'], {'metavar': '', 'type': 'string',
                         'action': 'callback', 'callback': read_config_file}),
         ("Show this program's version number and exit.",
          ['--version', '-V'], {'action': 'version'}),
         ('Show this help message and exit.',
          ['--help', '-h'], {'action': 'help'}),
         # Typically not useful for non-programmatical use.
         (SUPPRESS_HELP, ['--id-prefix'], {'default': ''}),
         (SUPPRESS_HELP, ['--auto-id-prefix'], {'default': 'id'}),
         # Hidden options, for development use only:
         (SUPPRESS_HELP, ['--dump-settings'], {'action': 'store_true'}),
         (SUPPRESS_HELP, ['--dump-internals'], {'action': 'store_true'}),
         (SUPPRESS_HELP, ['--dump-transforms'], {'action': 'store_true'}),
         (SUPPRESS_HELP, ['--dump-pseudo-xml'], {'action': 'store_true'}),
         (SUPPRESS_HELP, ['--expose-internal-attribute'],
          {'action': 'append', 'dest': 'expose_internals',
           'validator': validate_colon_separated_string_list}),
         (SUPPRESS_HELP, ['--strict-visitor'], {'action': 'store_true'}),
         ))
    """Runtime settings and command-line options common to all Docutils front
    ends.  Setting specs specific to individual Docutils components are also
    used (see `populate_from_components()`)."""

    settings_defaults = {'_disable_config': None,
                         '_source': None,
                         '_destination': None}
    """Defaults for settings that don't have command-line option equivalents."""

    relative_path_settings = ('warning_stream',)

    config_section = 'general'

    version_template = '%%prog (Docutils %s)' % docutils.__version__
    """Default version message."""

    def __init__(self, components=(), defaults=None, read_config_files=None,
                 *args, **kwargs):
        """
        `components` is a list of Docutils components each containing a
        ``.settings_spec`` attribute.  `defaults` is a mapping of setting
        default overrides.
        """

        self.lists = {}
        """Set of list-type settings."""

        optparse.OptionParser.__init__(
            self, option_class=Option, add_help_option=None,
            formatter=optparse.TitledHelpFormatter(width=78),
            *args, **kwargs)
        if not self.version:
            self.version = self.version_template
        # Make an instance copy (it will be modified):
        self.relative_path_settings = list(self.relative_path_settings)
        self.components = (self,) + tuple(components)
        self.populate_from_components(self.components)
        self.set_defaults(**(defaults or {}))
        if read_config_files and not self.defaults['_disable_config']:
            try:
                config_settings = self.get_standard_config_settings()
            except ValueError, error:
                self.error(error)
            self.set_defaults(**config_settings.__dict__)

    def populate_from_components(self, components):
        """
        For each component, first populate from the `SettingsSpec.settings_spec`
        structure, then from the `SettingsSpec.settings_defaults` dictionary.
        After all components have been processed, check for and populate from
        each component's `SettingsSpec.settings_default_overrides` dictionary.
        """
        for component in components:
            if component is None:
                continue
            settings_spec = component.settings_spec
            self.relative_path_settings.extend(
                component.relative_path_settings)
            for i in range(0, len(settings_spec), 3):
                title, description, option_spec = settings_spec[i:i+3]
                if title:
                    group = optparse.OptionGroup(self, title, description)
                    self.add_option_group(group)
                else:
                    group = self        # single options
                for (help_text, option_strings, kwargs) in option_spec:
                    option = group.add_option(help=help_text, *option_strings,
                                              **kwargs)
                    if kwargs.get('action') == 'append':
                        self.lists[option.dest] = 1
                if component.settings_defaults:
                    self.defaults.update(component.settings_defaults)
        for component in components:
            if component and component.settings_default_overrides:
                self.defaults.update(component.settings_default_overrides)

    def get_standard_config_files(self):
        """Return list of config files, from environment or standard."""
        try:
            config_files = os.environ['DOCUTILSCONFIG'].split(os.pathsep)
        except KeyError:
            config_files = self.standard_config_files
        return [os.path.expanduser(f) for f in config_files if f.strip()]

    def get_standard_config_settings(self):
        settings = Values()
        for filename in self.get_standard_config_files():
            settings.update(self.get_config_file_settings(filename), self)
        return settings

    def get_config_file_settings(self, config_file):
        """Returns a dictionary containing appropriate config file settings."""
        parser = ConfigParser()
        parser.read(config_file, self)
        base_path = os.path.dirname(config_file)
        applied = {}
        settings = Values()
        for component in self.components:
            if not component:
                continue
            for section in (tuple(component.config_section_dependencies or ())
                            + (component.config_section,)):
                if applied.has_key(section):
                    continue
                applied[section] = 1
                settings.update(parser.get_section(section), self)
        make_paths_absolute(
            settings.__dict__, self.relative_path_settings, base_path)
        return settings.__dict__

    def check_values(self, values, args):
        """Store positional arguments as runtime settings."""
        values._source, values._destination = self.check_args(args)
        make_paths_absolute(values.__dict__, self.relative_path_settings,
                            os.getcwd())
        return values

    def check_args(self, args):
        source = destination = None
        if args:
            source = args.pop(0)
            if source == '-':           # means stdin
                source = None
        if args:
            destination = args.pop(0)
            if destination == '-':      # means stdout
                destination = None
        if args:
            self.error('Maximum 2 arguments allowed.')
        if source and source == destination:
            self.error('Do not specify the same file for both source and '
                       'destination.  It will clobber the source file.')
        return source, destination

    def get_default_values(self):
        """Needed to get custom `Values` instances."""
        return Values(self.defaults)

    def get_option_by_dest(self, dest):
        """
        Get an option by its dest.

        If you're supplying a dest which is shared by several options,
        it is undefined which option of those is returned.

        A KeyError is raised if there is no option with the supplied
        dest.
        """
        for group in self.option_groups + [self]:
            for option in group.option_list:
                if option.dest == dest:
                    return option
        raise KeyError('No option with dest == %r.' % dest)


class ConfigParser(CP.ConfigParser):

    old_settings = {
        'pep_stylesheet': ('pep_html writer', 'stylesheet'),
        'pep_stylesheet_path': ('pep_html writer', 'stylesheet_path'),
        'pep_template': ('pep_html writer', 'template')}
    """{old setting: (new section, new setting)} mapping, used by
    `handle_old_config`, to convert settings from the old [options] section."""

    old_warning = """
The "[option]" section is deprecated.  Support for old-format configuration
files may be removed in a future Docutils release.  Please revise your
configuration files.  See ,
section "Old-Format Configuration Files".
"""

    def read(self, filenames, option_parser):
        if type(filenames) in (types.StringType, types.UnicodeType):
            filenames = [filenames]
        for filename in filenames:
            CP.ConfigParser.read(self, filename)
            if self.has_section('options'):
                self.handle_old_config(filename)
            self.validate_settings(filename, option_parser)

    def handle_old_config(self, filename):
        warnings.warn_explicit(self.old_warning, ConfigDeprecationWarning,
                               filename, 0)
        options = self.get_section('options')
        if not self.has_section('general'):
            self.add_section('general')
        for key, value in options.items():
            if self.old_settings.has_key(key):
                section, setting = self.old_settings[key]
                if not self.has_section(section):
                    self.add_section(section)
            else:
                section = 'general'
                setting = key
            if not self.has_option(section, setting):
                self.set(section, setting, value)
        self.remove_section('options')

    def validate_settings(self, filename, option_parser):
        """
        Call the validator function and implement overrides on all applicable
        settings.
        """
        for section in self.sections():
            for setting in self.options(section):
                try:
                    option = option_parser.get_option_by_dest(setting)
                except KeyError:
                    continue
                if option.validator:
                    value = self.get(section, setting, raw=1)
                    try:
                        new_value = option.validator(
                            setting, value, option_parser,
                            config_parser=self, config_section=section)
                    except Exception, error:
                        raise (ValueError(
                            'Error in config file "%s", section "[%s]":\n'
                            '    %s: %s\n        %s = %s'
                            % (filename, section, error.__class__.__name__,
                               error, setting, value)), None, sys.exc_info()[2])
                    self.set(section, setting, new_value)
                if option.overrides:
                    self.set(section, option.overrides, None)

    def optionxform(self, optionstr):
        """
        Transform '-' to '_' so the cmdline form of option names can be used.
        """
        return optionstr.lower().replace('-', '_')

    def get_section(self, section):
        """
        Return a given section as a dictionary (empty if the section
        doesn't exist).
        """
        section_dict = {}
        if self.has_section(section):
            for option in self.options(section):
                section_dict[option] = self.get(section, option, raw=1)
        return section_dict


class ConfigDeprecationWarning(DeprecationWarning):
    """Warning for deprecated configuration file features."""
Zope-2.9.4-retire_zpkg/lib/python/docutils/THANKS.txt0000644000175000017500000000505210172235404022340 0ustar  tseavertseaverAcknowledgements
================

:Author: David Goodger
:Contact: goodger@python.org
:Date: $Date: 2005/01/07 15:11:43 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: This document has been placed in the public domain.

I would like to acknowledge the people who have made a direct impact
on the Docutils project, knowingly or not, in terms of encouragement,
suggestions, criticism, bug reports, code contributions, cash
donations, tasty treats, and related projects:

* Aahz
* David Abrahams
* David Ascher
* Heiko Baumann
* Eric Bellot
* Ian Bicking
* Marek Blaha
* Martin Blais
* Stephen Boulet
* Fred Bremmer
* Simon Budig
* Bill Bumgarner
* Brett Cannon
* Greg Chapman
* Nicolas Chauveau
* Beni Cherniavsky
* Adam Chodorowski
* Brent Cook
* Laura Creighton
* Artur de Sousa Rocha
* Stephan Deibel & `Wing IDE `__
* Jason Diamond
* William Dode
* Fred Drake
* Reggie Dugard
* Dethe Elza
* Marcus Ertl
* Benja Fallenstein
* fantasai
* Stefane Fermigier
* Jim Fulton
* Peter Funk
* Lele Gaifax
* Dinu C. Gherman
* Matt Gilbert
* Jorge Gonzalez
* Engelbert Gruber
* Jacob Hallen
* Simon Hefti
* Doug Hellmann
* Marc Herbert
* Juergen Hermann
* Jannie Hofmeyr
* Steve Holden
* Michael Hudson
* Marcelo Huerta San Martin
* Ludger Humbert
* Jeremy Hylton
* Tony Ibbs
* Alan Jaffray
* Joe YS Jaw
* Dmitry Jemerov
* Richard Jones
* Andreas Jung
* Garth Kidd
* Axel Kollmorgen
* Jeff Kowalczyk
* Dave Kuhlman
* Lloyd Kvam
* Kirill Lapshin
* Nicola Larosa
* Daniel Larsson
* Marc-Andre Lemburg
* Julien Letessier
* Wolfgang Lipp
* Edward Loper
* Dallas Mahrt
* Ken Manheimer
* Bob Marshall
* Mark McEahern
* Vincent McIntyre
* John F Meinel Jr
* Skip Montanaro
* Paul Moore
* Nigel W. Moriarty
* Mark Nodine
* Patrick K. O'Brien
* Michel Pelletier
* Sam Penrose
* Tim Peters
* Pearu Peterson
* Mark Pilgrim
* Brett g Porter
* David Priest
* Jens Quade
* Andy Robinson
* Tavis Rudd
* Tracy Ruggles
* Oliver Rutherfurd
* Luc Saffre
* Kenichi Sato
* Ueli Schlaepfer
* Gunnar Schwant
* Bill Sconce
* Frank Siebenlist
* Bruce Smith
* Asko Soukka
* Darek Suchojad
* Roman Suzi
* Janet Swisher
* tav
* Kent Tenney
* Bob Tolbert
* Paul Tremblay
* Laurence Tratt
* Adrian van den Dries
* Guido van Rossum
* Miroslav Vasko
* Paul Viren
* Martin von Loewis
* Greg Ward
* Barry Warsaw
* Edward Welbourne
* Felix Wiemann
* Ka-Ping Yee
* Moshe Zadka

Thank you!

Special thanks to `SourceForge `__ and the
`Python Software Foundation `__.

Hopefully I haven't forgotten anyone or misspelled any names;
apologies (and please let me know!) if I have.
Zope-2.9.4-retire_zpkg/lib/python/docutils/PKG-INFO0000644000175000017500000000323710172235404021707 0ustar  tseavertseaverMetadata-Version: 1.0
Name: docutils
Version: 0.3.7
Summary: Docutils -- Python Documentation Utilities
Home-page: http://docutils.sourceforge.net/
Author: David Goodger
Author-email: goodger@users.sourceforge.net
License: public domain, Python, BSD, GPL (see COPYING.txt)
Description: Docutils is a modular system for processing documentation
        into useful formats, such as HTML, XML, and LaTeX.  For
        input Docutils supports reStructuredText, an easy-to-read,
        what-you-see-is-what-you-get plaintext markup syntax.
Platform: OS-independent
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Intended Audience :: Other Audience
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: Public Domain
Classifier: License :: OSI Approved :: Python Software Foundation License
Classifier: License :: OSI Approved :: BSD License
Classifier: License :: OSI Approved :: GNU General Public License (GPL)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing
Classifier: Natural Language :: English
Classifier: Natural Language :: Afrikaans
Classifier: Natural Language :: Esperanto
Classifier: Natural Language :: French
Classifier: Natural Language :: German
Classifier: Natural Language :: Italian
Classifier: Natural Language :: Russian
Classifier: Natural Language :: Slovak
Classifier: Natural Language :: Spanish
Classifier: Natural Language :: Swedish
Zope-2.9.4-retire_zpkg/lib/python/docutils/README.txt0000644000175000017500000002650210172235404022310 0ustar  tseavertseaver==================
 README: Docutils
==================

:Author: David Goodger
:Contact: goodger@users.sourceforge.net
:Date: $Date: 2005/01/07 15:11:43 $
:Web site: http://docutils.sourceforge.net/
:Copyright: This document has been placed in the public domain.

.. contents::


Thank you for downloading the Python Docutils project archive.  As
this is a work in progress, please check the project website for
updated working files (snapshots).  This project should be considered
highly experimental; APIs are subject to change at any time.


Quick-Start
===========

This is for those who want to get up & running quickly.  Read on for
complete details.

1. Get and install the latest release of Python, available from

       http://www.python.org/

   Python 2.2 or later [1]_ is required; Python 2.2.2 or later is
   recommended.

2. Use the latest Docutils code.  Get the code from CVS or from the
   snapshot:

       http://docutils.sf.net/docutils-snapshot.tgz

   See `Releases & Snapshots`_ below for details.

3. Unpack the tarball in a temporary directory (**not** directly in
   Python's ``site-packages``) and install with the standard ::

       python setup.py install

   See Installation_ below for details.

4. Use a front-end tool from the "tools" subdirectory of the same
   directory as in step 3.  For example::

       cd tools
       ./rst2html.py ../FAQ.txt ../FAQ.html        (Unix)
       python rst2html.py ..\FAQ.txt ..\FAQ.html   (Windows)

   See Usage_ below for details.


Purpose
=======

The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and TeX.  Support for the following sources has been implemented:

* Standalone files.

* `PEPs (Python Enhancement Proposals)`_.

Support for the following sources is planned:

* Inline documentation from Python modules and packages, extracted
  with namespace context.  **This is the focus of the current
  development effort.**

* Email (RFC-822 headers, quoted excerpts, signatures, MIME parts).

* Wikis, with global reference lookups of "wiki links".

* Compound documents, such as multiple chapter files merged into a
  book.

* And others as discovered.

.. _PEPs (Python Enhancement Proposals):
   http://www.python.org/peps/pep-0012.html


Releases & Snapshots
====================

Putting together an official "Release" of Docutils is a significant
effort, so it isn't done that often.  In the meantime, the CVS
snapshots always contain the latest code and documentation, usually
updated within an hour of changes being committed to the repository,
and usually bug-free:

* Snapshot of Docutils code, documentation, front-end tools, and
  tests: http://docutils.sf.net/docutils-snapshot.tgz

* Snapshot of the Sandbox (experimental, contributed code):
  http://docutils.sf.net/docutils-sandbox-snapshot.tgz

* Snapshot of web files (the files that generate the web site):
  http://docutils.sf.net/docutils-web-snapshot.tgz

To keep up to date on the latest developments, download fresh copies
of the snapshots regularly.  New functionality is being added weekly,
sometimes daily.  (There's also the CVS repository, and a mailing list
for CVS messages.  See the web site [address above] or
docs/dev/policies.txt for details.)


Requirements
============

To run the code, Python 2.2 or later [1]_ must already be installed.
The latest release is recommended.  Python is available from
http://www.python.org/.

The `Python Imaging Library`, or PIL, is used for some image
manipulation operations if it is installed.

Docutils uses Greg Ward's Optik_/optparse option processing package.
It is included in the Docutils distribution.  Python 2.3 and later
come with optparse in the standard library; in this case, the Docutils
copy is not installed.

.. [1] Python 2.1 may be used providing the compiler package is
   installed.  The compiler package can be found in the Tools/
   directory of Python 2.1's source distribution.

.. _Python Imaging Library: http://www.pythonware.com/products/pil/
.. _Optik: http://optik.sourceforge.net/


Project Files & Directories
===========================

* README.txt: You're reading it.

* COPYING.txt: Public Domain Dedication and copyright details for
  non-public-domain files (most are PD).

* FAQ.txt: Docutils Frequently Asked Questions.

* HISTORY.txt: Release notes for the current and previous project
  releases.

* setup.py: Installation script.  See "Installation" below.

* install.py: Quick & dirty installation script.  Just run it.  For
  any kind of customization or help though, setup.py must be used.

* docutils: The project source directory, installed as a Python
  package.

* extras: Directory for third-party modules that Docutils depends on.
  These are only installed if they're not already present.

* docs: The project documentation directory.  Read ``docs/index.txt``
  for an overview, which is especially interesting for developers.

* docs/user: The project user documentation directory.  Contains the
  following documents, among others:

  - docs/user/tools.txt: Docutils Front-End Tools
  - docs/user/latex.txt: Docutils LaTeX Writer
  - docs/user/rst/quickstart.txt: A ReStructuredText Primer
  - docs/user/rst/quickref.html: Quick reStructuredText (HTML only)

* docs/ref: The project reference directory.
  ``docs/ref/rst/restructuredtext.txt`` is the reStructuredText
  reference.

* licenses: Directory containing copies of license files for
  non-public-domain files.

* tools: Directory for Docutils front-end tools.  See
  ``docs/user/tools.txt`` for documentation.

* test: Unit tests.  Not required to use the software, but very useful
  if you're planning to modify it.  See `Running the Test Suite`_
  below.


Installation
============

The first step is to expand the ``.tar.gz`` or ``.tgz`` archive in a
temporary directory (**not** directly in Python's ``site-packages``).
It contains a distutils setup file "setup.py".  OS-specific
installation instructions follow.


GNU/Linux, BSDs, Unix, Mac OS X, etc.
-------------------------------------

1. Open a shell.

2. Go to the directory created by expanding the archive::

       cd 

3. Install the package::

       python setup.py install

   If the python executable isn't on your path, you'll have to specify
   the complete path, such as /usr/local/bin/python.  You may need
   root permissions to complete this step.

You can also just run install.py; it does the same thing.


Windows
-------

1. Open a DOS box (Command Shell, MSDOS Prompt, or whatever they're
   calling it these days).

2. Go to the directory created by expanding the archive::

       cd 

3. Install the package::

       \python setup.py install

If your system is set up to run Python when you double-click on .py
files, you can run install.py to do the same as the above.


Mac OS 8/9
----------

1. Open the folder containing the expanded archive.

2. Double-click on the file "setup.py", which should be a "Python
   module" file.

   If the file isn't a "Python module", the line endings are probably
   also wrong, and you will need to set up your system to recognize
   ".py" file extensions as Python files.  See
   http://gotools.sourceforge.net/mac/python.html for detailed
   instructions.  Once set up, it's easiest to start over by expanding
   the archive again.

3. The distutils options window will appear.  From the "Command" popup
   list choose "install", click "Add", then click "OK".

If install.py is a "Python module" (see step 2 above if it isn't), you
can run it (double-click) instead of the above.  The distutils options
window will not appear.


Usage
=====

After unpacking and installing the Docutils package, the following
shell commands will generate HTML for all included documentation::

    cd /tools
    ./buildhtml.py ../

On Windows systems, type::

    cd \tools
    python buildhtml.py ..

The final directory name of the ```` is
"docutils" for snapshots.  For official releases, the directory may be
called "docutils-X.Y.Z", where "X.Y.Z" is the release version.
Alternatively::

    cd 
    tools/buildhtml.py --config=tools/docutils.conf          (Unix)
    python tools\buildhtml.py --config=tools\docutils.conf   (Windows)

Some files may generate system messages (warnings and errors).  The
``docs/user/rst/demo.txt`` file (under the archive directory) contains
5 intentional errors.  (They test the error reporting mechanism!)

There are many front-end tools in the unpacked "tools" subdirectory.
You may want to begin with the "rst2html.py" front-end tool.  Most
tools take up to two arguments, the source path and destination path,
with STDIN and STDOUT being the defaults.  Use the "--help" option to
the front-end tools for details on options and arguments.  See
Docutils Front-End Tools (``docs/user/tools.txt``) for full documentation.

The package modules are continually growing and evolving.  The
``docutils.statemachine`` module is usable independently.  It contains
extensive inline documentation (in reStructuredText format of course).

Contributions are welcome!


Running the Test Suite
======================

To run the entire test suite, after installation_ open a shell and use
the following commands::

    cd /test
    ./alltests.py

Under Windows, type::

    cd \test
    python alltests.py

You should see a long line of periods, one for each test, and then a
summary like this::

    Ran 518 tests in 24.653s

    OK
    Elapsed time: 26.189 seconds

The number of tests will grow over time, and the times reported will
depend on the computer running the tests.  The difference between the
two times represents the time required to set up the tests (import
modules, create data structures, etc.).

If any of the tests fail, please `open a bug report`_ or `send email`_
[2]_.  Please include all relevant output, information about your
operating system, Python version, and Docutils version.  To see the
Docutils version, use these commands in the shell::

    cd ../tools
    ./quicktest.py --version

Windows users type these commands::

    cd ..\tools
    python quicktest.py --version

.. _open a bug report:
   http://sourceforge.net/tracker/?group_id=38414&atid=422030
.. _send email: mailto:docutils-users@lists.sourceforge.net
   ?subject=Docutils%20test%20suite%20failure


Getting Help
============

If you have questions or need assistance with Docutils or
reStructuredText, please `post a message`_ to the `Docutils-Users
mailing list`_ [2]_.

.. [2] Due to overwhelming amounts of spam, the
   docutils-users@lists.sourceforge.net mailing list has been set up
   for subscriber posting only.  Non-subscribers who post to
   docutils-users will receive a message with "Subject: Your message
   to Docutils-users awaits moderator approval".  Legitimate messages
   are accepted and posted as soon as possible (a list administrator
   must verify the message manually).  If you'd like to subscribe to
   docutils-users, please visit
   .

.. _post a message: mailto:docutils-users@lists.sourceforge.net
.. _Docutils-Users mailing list:
   http://lists.sourceforge.net/lists/listinfo/docutils-users


..
   Local Variables:
   mode: indented-text
   indent-tabs-mode: nil
   sentence-end-double-space: t
   fill-column: 70
   End:
Zope-2.9.4-retire_zpkg/lib/python/docutils/BUGS.txt0000644000175000017500000002105610172235404022112 0ustar  tseavertseaver================
 Docutils_ Bugs
================

:Author: David Goodger; open to all Docutils developers
:Contact: goodger@python.org
:Date: $Date: 2005/01/07 15:11:43 $
:Revision: $Revision: 1.1.2.1 $
:Copyright: This document has been placed in the public domain.

.. _Docutils: http://docutils.sourceforge.net/


Bugs in Docutils?!?  Yes, we do have a few.  Some are old-timers that
tend to stay in the shadows and don't bother anybody.  Once in a while
new bugs are born.  From time to time some bugs (new and old) crawl
out into the light and must be dealt with.  Icky.

This document describes how to report a bug, and lists known bugs.

.. contents::


How To Report A Bug
===================

If you think you've discovered a bug, please read through these
guidelines before reporting it.

First, make sure it's a new bug:

* Please check the list of `known bugs`_ below and the `SourceForge
  Bug Tracker`_ to see if it has already been reported.

* Are you using the very latest version of Docutils?  The bug may have
  already been fixed.  Please get the latest version of Docutils from
  CVS_ or from the `development snapshot`_ and check again.  Even if
  your bug has not been fixed, others probably have, and you're better
  off with the most up-to-date code.

  If you don't have time to check the latest snapshot, please report
  the bug anyway.  We'd rather tell you that it's already fixed than
  miss reports of unfixed bugs.

* If Docutils does not behave the way you expect, look in the
  documentation_ (don't forget the FAQ_!) and `mailing list archives`_
  for evidence that it should behave the way you expect.

If you're not sure, please ask on the
docutils-users@lists.sourceforge.net [1]_ mailing list first.

If it's a new bug, the most important thing you can do is to write a
simple description and a recipe that reproduces the bug.  Try to
create a minimal document that demonstrates the bug.  The easier you
make it to understand and track down the bug, the more likely a fix
will be.

Now you're ready to write the bug report.  Please include:

* A clear description of the bug.  Describe how you expected Docutils
  to behave, and contrast that with how it actually behaved.  While
  the bug may seem obvious to you, it may not be so obvious to someone
  else, so it's best to avoid a guessing game.

* A complete description of the environment in which you reproduced
  the bug:

  - Your operating system & version.
  - The version of Python (``python -V``).
  - The version of Docutils (use the "-V" option to most Docutils
    front-end tools).
  - Any private modifications you made to Docutils.
  - Anything else that could possibly be relevant.  Err on the side
    of too much information, rather than too little.

* A literal transcript of the *exact* command you ran, and the *exact*
  output.  Use the "--traceback" option to get a complete picture.

* The exact input and output files.  Better to attach complete files
  to your bug report than to include just a summary or excerpt.

* If you also want to include speculation as to the cause, and even a
  patch to fix the bug, that would be great!

The best place to send your bug report is to the `SourceForge Bug
Tracker`_.  That way, it won't be misplaced or forgotten.  In fact, an
open bug report on SourceForge is a constant irritant that begs to be
squashed.

Thank you!

(This section was inspired by the `Subversion project's`__ BUGS__
file.)

.. [1] Due to overwhelming amounts of spam, the
   docutils-users@lists.sourceforge.net mailing list has been set up
   for subscriber posting only.  Non-subscribers who post to
   docutils-users will receive a message with "Subject: Your message
   to Docutils-users awaits moderator approval".  Legitimate messages
   are accepted and posted as soon as possible (a list administrator
   must verify the message manually).  If you'd like to subscribe to
   docutils-users, please visit
   .

__ http://subversion.tigris.org/
__ http://svn.collab.net/viewcvs/svn/trunk/BUGS?view=markup

.. _CVS: http://sourceforge.net/cvs/?group_id=38414
.. _development snapshot: http://docutils.sf.net/#development-snapshot
.. _documentation: docs/
.. _FAQ: FAQ.html
.. _mailing list archives: http://docutils.sf.net/#mailing-lists
.. _SourceForge Bug Tracker:
   http://sourceforge.net/tracker/?group_id=38414&atid=422030


Known Bugs
==========

Also see the `SourceForge Bug Tracker`_.

* .. _unencoded stylesheet reference:

  ``--stylesheet='foo&bar'`` causes an invalid stylesheet reference to
  be inserted in an HTML file, because the ``&`` isn't encoded as
  ``&``.

* ``utils.relative_path()`` sometimes returns absolute _`paths on
  Windows` (like ``C:/test/foo.css``) where it could have chosen a
  relative path.

  Furthermore, absolute pathnames are inserted verbatim, like
  ``href="C:/test/foo.css"`` instead of
  ``href="file:///C:/test/foo.css"``.

  For details, see `this posting by Alan G. Isaac
  `_.

* .. _empty csv-table:

  When supplying an empty file for the csv-table directive, Docutils
  crashes with a zero-division error.  Example::

      .. csv-table::
         :file: empty.txt

* _`Line numbers` in system messages are inconsistent in the parser.

  - In text inserted by the "include" directive, errors are often not
    reported with the correct "source" or "line" numbers.  Perhaps all
    Reporter calls need "source" and "line" keyword arguments.
    Elements' .line assignments should be checked.  (Assign to .source
    too?  Add a set_info method?  To what?)  There's a test in
    test/test_parsers/test_rst/test_directives/test_include.py.

  - Some line numbers in elements are not being set properly
    (explicitly), just implicitly/automatically.  See rev. 1.74 of
    docutils/parsers/rst/states.py for an example of how to set.

* .. _none source:

  Quite a few nodes are getting a "None" source attribute as well.  In
  particular, see the bodies of definition lists.

* .. _mislocated targets:

  Explicit targets are sometimes mis-located.  In particular, placing
  a target before a section header puts the target at the end of the
  previous section instead of the start of the next section.  The code
  in docutils.transforms.misc.ClassAttribute could be used to fix
  this.  (Reported by David Priest.)

* David Abrahams pointed out that _`doubly-indirect substitutions`
  have a bug, but only when there's multiple references::

      |substitute| my coke for gin
      |substitute| you for my mum
      at least I'll get my washing done

      .. |substitute| replace:: |replace|
      .. |replace| replace:: swap

  This is tricky.  Substitutions have to propagate back completely.

* .. _substitutions and references:

  Another bug from David Abrahams (run with ``rst2html.py --traceback``)::

      |substitution| and again a |substitution|.

      .. |substitution| replace:: ref__

      __ a.html
      __ b.html

  Change the references.Substitutions tranform's priority from 220 to
  680, so it happens after reference resolution?  Then we have to deal
  with multiple IDs.  Perhaps the Substitution transform should remove
  all IDs from definitions after the first substitution reference is
  processed.

* Footnote label "5" should be "4"::

      $ rst2pseudoxml.py < ref [#abc]_ [#]_ [1]_ [#4]_
      > 
      > .. [#abc] footnote
      > .. [#] two
      > .. [1] one
      > .. [#4] four
      > EOF
      
          
              ref 
              
                  2
               
              
                  3
               
              
                  1
               
              
                  5