[py-svn] pylib commit 50db633de97b: redo documentation for pylib: convert to sphinx, add an enhance.
commits-noreply at bitbucket.org
commits-noreply at bitbucket.org
Sun Nov 7 17:19:54 CET 2010
# HG changeset patch -- Bitbucket.org
# Project pylib
# URL http://bitbucket.org/hpk42/pylib/overview
# User holger krekel <holger at merlinux.eu>
# Date 1289146873 -3600
# Node ID 50db633de97b3626c0a07fbe8911856e2c14988b
# Parent cc6128f129a0d2723c998efc521b2158f91762aa
redo documentation for pylib: convert to sphinx, add an enhance.
--- /dev/null
+++ b/doc/Makefile
@@ -0,0 +1,130 @@
+# Makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS =
+SPHINXBUILD = sphinx-build
+PAPER =
+BUILDDIR = _build
+
+# Internal variables.
+PAPEROPT_a4 = -D latex_paper_size=a4
+PAPEROPT_letter = -D latex_paper_size=letter
+ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
+
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest
+
+help:
+ @echo "Please use \`make <target>' where <target> is one of"
+ @echo " html to make standalone HTML files"
+ @echo " dirhtml to make HTML files named index.html in directories"
+ @echo " singlehtml to make a single large HTML file"
+ @echo " pickle to make pickle files"
+ @echo " json to make JSON files"
+ @echo " htmlhelp to make HTML files and a HTML help project"
+ @echo " qthelp to make HTML files and a qthelp project"
+ @echo " devhelp to make HTML files and a Devhelp project"
+ @echo " epub to make an epub"
+ @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
+ @echo " latexpdf to make LaTeX files and run them through pdflatex"
+ @echo " text to make text files"
+ @echo " man to make manual pages"
+ @echo " changes to make an overview of all changed/added/deprecated items"
+ @echo " linkcheck to check all external links for integrity"
+ @echo " doctest to run all doctests embedded in the documentation (if enabled)"
+
+clean:
+ -rm -rf $(BUILDDIR)/*
+
+html:
+ $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
+
+dirhtml:
+ $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
+ @echo
+ @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
+
+singlehtml:
+ $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
+ @echo
+ @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
+
+pickle:
+ $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
+ @echo
+ @echo "Build finished; now you can process the pickle files."
+
+json:
+ $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
+ @echo
+ @echo "Build finished; now you can process the JSON files."
+
+htmlhelp:
+ $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
+ @echo
+ @echo "Build finished; now you can run HTML Help Workshop with the" \
+ ".hhp project file in $(BUILDDIR)/htmlhelp."
+
+qthelp:
+ $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
+ @echo
+ @echo "Build finished; now you can run "qcollectiongenerator" with the" \
+ ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
+ @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pylib.qhcp"
+ @echo "To view the help file:"
+ @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pylib.qhc"
+
+devhelp:
+ $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
+ @echo
+ @echo "Build finished."
+ @echo "To view the help file:"
+ @echo "# mkdir -p $$HOME/.local/share/devhelp/pylib"
+ @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pylib"
+ @echo "# devhelp"
+
+epub:
+ $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
+ @echo
+ @echo "Build finished. The epub file is in $(BUILDDIR)/epub."
+
+latex:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo
+ @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
+ @echo "Run \`make' in that directory to run these through (pdf)latex" \
+ "(use \`make latexpdf' here to do that automatically)."
+
+latexpdf:
+ $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
+ @echo "Running LaTeX files through pdflatex..."
+ make -C $(BUILDDIR)/latex all-pdf
+ @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
+
+text:
+ $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
+ @echo
+ @echo "Build finished. The text files are in $(BUILDDIR)/text."
+
+man:
+ $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
+ @echo
+ @echo "Build finished. The manual pages are in $(BUILDDIR)/man."
+
+changes:
+ $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
+ @echo
+ @echo "The overview file is in $(BUILDDIR)/changes."
+
+linkcheck:
+ $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
+ @echo
+ @echo "Link check complete; look for any errors in the above output " \
+ "or in $(BUILDDIR)/linkcheck/output.txt."
+
+doctest:
+ $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
+ @echo "Testing of doctests in the sources finished, look at the " \
+ "results in $(BUILDDIR)/doctest/output.txt."
--- a/doc/install.txt
+++ b/doc/install.txt
@@ -1,128 +1,50 @@
-.. _`index page`: http://pypi.python.org/pypi/py/
+.. _`pylib`:
+.. _`index page`: http://pypi.python.org/pypi/pylib/
-py.test/pylib installation info in a nutshell
+installation info in a nutshell
===================================================
-**Pythons**: 2.4, 2.5, 2.6, 2.7, 3.0, 3.1.x, Jython-2.5.1, PyPy-1.2
+**PyPI name**: pylib_
+
+**Pythons**: 2.4, 2.5, 2.6, 2.7, 3.0, 3.1.x, Jython-2.5.1, PyPy-1.3
**Operating systems**: Linux, Windows, OSX, Unix
**Requirements**: setuptools_ or Distribute_
-**Installers**: easy_install_ and pip_ or `standalone`_ (new for 1.2)
+**Installers**: ``easy_install`` and ``pip``
-**Distribution names**:
+**hg repository**: https://bitbucket.org/hpk42/pylib
-* PyPI name: ``py`` (see `index page`_ for versions)
-* redhat fedora: ``python-py``
-* debian: ``python-codespeak-lib``
-* gentoo: ``pylib``
-**Installed scripts**: see `bin`_ for which and how scripts are installed.
-
-**hg repository**: https://bitbucket.org/hpk42/py-trunk
-
-.. _`bin`: bin.html
-
-
-.. _`easy_install`:
-
-Installation using easy_install
-===================================================
+easy install
+-----------------------------
Both `Distribute`_ and setuptools_ provide the ``easy_install``
installation tool with which you can type into a command line window::
- easy_install -U py
+ easy_install -U pylib
-to install the latest release of the py lib and py.test. The ``-U`` switch
+to install the latest release of the py lib. The ``-U`` switch
will trigger an upgrade if you already have an older version installed.
Note that setuptools works ok with Python2 interpreters while `Distribute`_
additionally works with Python3 and also avoid some issues on Windows.
-Known issues:
-
-- **Windows**: If "easy_install" or "py.test" are not found
- please see here for preparing your environment for running
- command line tools: `Python for Windows`_. You may alternatively
- use an `ActivePython install`_ which makes command line tools
- automatically available under Windows.
-
-.. _`ActivePython install`: http://www.activestate.com/activepython/downloads
-
-.. _`Jython does not create command line launchers`: http://bugs.jython.org/issue1491
-
-- **Jython2.5.1 on Windows XP**: `Jython does not create command line launchers`_
- so ``py.test`` will not work correctly. You may install py.test on
- CPython and type ``py.test --genscript=mytest`` and then use
- ``jython mytest`` to run py.test for your tests to run in Jython.
-
-- **On Linux**: If ``easy_install`` fails because it needs to run
- as the superuser you are trying to install things globally
- and need to put ``sudo`` in front of the command.
-
-
-.. _quickstart: test/quickstart.html
-
-
-Recommendation: install tool and dependencies virtually
-===========================================================
-
-It is recommended to work with virtual environments
-(e.g. virtualenv_ or buildout_ based) and use easy_install_
-(or pip_) for installing py.test/pylib and any dependencies
-you need to run your tests. Local virtual Python environments
-(as opposed to system-wide "global" environments) make for a more
-reproducible and reliable test environment.
-
-.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
-.. _`buildout`: http://www.buildout.org/
-.. _pip: http://pypi.python.org/pypi/pip
-
-.. _standalone:
-
-Generating a py.test standalone Script
-============================================
-
-If you are a maintainer or application developer and want users
-to run tests you can use a facility to generate a standalone
-"py.test" script that you can tell users to run::
-
- py.test --genscript=mytest
-
-will generate a ``mytest`` script that is, in fact, a ``py.test`` under
-disguise. You can tell people to download and then e.g. run it like this::
-
- python mytest --pastebin=all
-
-and ask them to send you the resulting URL. The resulting script has
-all core features and runs unchanged under Python2 and Python3 interpreters.
-
-.. _`Python for Windows`: http://www.imladris.com/Scripts/PythonForWindows.html
-
-.. _mercurial: http://mercurial.selenic.com/wiki/
-.. _`Distribute`:
-.. _`Distribute for installation`: http://pypi.python.org/pypi/distribute#installation-instructions
-.. _`distribute installation`: http://pypi.python.org/pypi/distribute
-.. _checkout:
-.. _tarball:
-
Working from version control or a tarball
-=================================================
+-----------------------------------------------
To follow development or start experiments, checkout the
complete code and documentation source with mercurial_::
- hg clone https://bitbucket.org/hpk42/py-trunk/
+ hg clone https://bitbucket.org/hpk42/pylib
Development takes place on the 'trunk' branch.
You can also go to the python package index and
download and unpack a TAR file::
- http://pypi.python.org/pypi/py/
-
+ http://pypi.python.org/pypi/pylib/
activating a checkout with setuptools
--------------------------------------------
@@ -137,52 +59,26 @@ in order to work inline with the tools a
.. _`directly use a checkout`:
-directly use a checkout or tarball / avoid setuptools
--------------------------------------------------------------
-
-Get a checkout_ or tarball_ and add paths to your environment variables:
-
-* ``PYTHONPATH`` needs to contain the root directory (where ``py`` resides)
-* ``PATH`` needs to contain ``ROOT/bin`` or ``ROOT\bin\win32`` respectively.
-
-There also are helper scripts that set the variables accordingly. On windows
-execute::
-
- # inside autoexec.bat or shell startup
- c:\\path\to\checkout\bin\env.cmd
-
-on linux/OSX add this to your shell initialization::
-
- # inside e.g. .bashrc
- eval `python ~/path/to/checkout/bin/env.py`
-
-both of which which will get you good settings. If you install
-the pylib this way you can easily ``hg pull && hg up`` or download
-a new tarball_ to follow the development tree.
-
-
-Note that the scripts manually added like this will look for
-py libs in the chain of parent directories of the current working dir.
-For example, if you have a layout like this::
-
- mypkg/
- subpkg1/
- tests/
- tests/
- py/
-
-issuing ``py.test subpkg1`` will use the py lib
-from that projects root directory. If in doubt over where
-the pylib comes from you can always do::
-
- py.test --version
-
-to see where py.test is imported from.
-
-.. _`command line scripts`: bin.html
-.. _contact: contact.html
-
-.. _`RPM`: http://translate.sourceforge.net/releases/testing/fedora/pylib-0.9.2-1.fc9.noarch.rpm
-
.. _`setuptools`: http://pypi.python.org/pypi/setuptools
+
+Contact and Communication points
+--------------------------------------
+
+- `py-dev developers list`_ and `commit mailing list`_.
+
+- #pylib on irc.freenode.net IRC channel for random questions.
+
+- `bitbucket issue tracker`_ use this bitbucket issue tracker to report
+ bugs or request features.
+
+.. _`bitbucket issue tracker`: http://bitbucket.org/hpk42/pylib/issues/
+
+.. _codespeak: http://codespeak.net/
+.. _`py-dev`:
+.. _`development mailing list`:
+.. _`py-dev developers list`: http://codespeak.net/mailman/listinfo/py-dev
+.. _`py-svn`:
+.. _`commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn
+
+.. include:: links.inc
--- a/py/_path/common.py
+++ b/py/_path/common.py
@@ -36,7 +36,7 @@ class Checkers:
return self.path.relto(arg)
def fnmatch(self, arg):
- return FNMatcher(arg)(self.path)
+ return self.path.fnmatch(arg)
def endswith(self, arg):
return str(self.path).endswith(arg)
@@ -161,22 +161,45 @@ newline will be removed from the end of
return repr(str(self))
def check(self, **kw):
- """ check a path for existence, or query its properties
+ """ check a path for existence and properties.
- without arguments, this returns True if the path exists (on the
- filesystem), False if not
+ Without arguments, return True if the path exists, otherwise False.
- with (keyword only) arguments, the object compares the value
- of the argument with the value of a property with the same name
- (if it has one, else it raises a TypeError)
+ valid checkers::
- when for example the keyword argument 'ext' is '.py', this will
- return True if self.ext == '.py', False otherwise
+ file=1 # is a file
+ file=0 # is not a file (may not even exist)
+ dir=1 # is a dir
+ link=1 # is a link
+ exists=1 # exists
+
+ You can specify multiple checker definitions, for example::
+
+ path.check(file=1, link=1) # a link pointing to a file
"""
if not kw:
kw = {'exists' : 1}
return self.Checkers(self)._evaluate(kw)
+ def fnmatch(self, pattern):
+ """return true if the basename/fullname matches the glob-'pattern'.
+
+ valid pattern characters::
+
+ * matches everything
+ ? matches any single character
+ [seq] matches any character in seq
+ [!seq] matches any char not in seq
+
+ If the pattern contains a path-separator then the full path
+ is used for pattern matching and a '*' is prepended to the
+ pattern.
+
+ if the pattern doesn't contain a path-separator the pattern
+ is only matched against the basename.
+ """
+ return FNMatcher(pattern)(self)
+
def relto(self, relpath):
""" return a string which is the relative part of the path
to the given 'relpath'.
@@ -339,20 +362,6 @@ class FNMatcher:
def __init__(self, pattern):
self.pattern = pattern
def __call__(self, path):
- """return true if the basename/fullname matches the glob-'pattern'.
-
- * matches everything
- ? matches any single character
- [seq] matches any character in seq
- [!seq] matches any char not in seq
-
- if the pattern contains a path-separator then the full path
- is used for pattern matching and a '*' is prepended to the
- pattern.
-
- if the pattern doesn't contain a path-separator the pattern
- is only matched against the basename.
- """
pattern = self.pattern
if pattern.find(path.sep) == -1:
name = path.basename
--- a/doc/io.txt
+++ b/doc/io.txt
@@ -41,3 +41,19 @@ filedescriptors you may invoke::
>>> out,err = capture.reset()
>>> err
'world'
+
+py.io object reference
+============================
+
+.. autoclass:: py.io.StdCaptureFD
+ :members:
+ :inherited-members:
+
+.. autoclass:: py.io.StdCapture
+ :members:
+ :inherited-members:
+
+.. autoclass:: py.io.TerminalWriter
+ :members:
+ :inherited-members:
+
--- a/CHANGELOG
+++ b/CHANGELOG
@@ -5,8 +5,8 @@ Changes between 1.3.4 and 2.0.0dev0
- py.test was moved to a separate "pytest" package. What remains is
a stub hook which will proxy ``import py.test`` to ``pytest``.
- all command line tools ("py.cleanup/lookup/countloc/..." moved
- to "pytools" package)
-- removed the old deprecated "py.magic" namespace
+ to "pycmd" package)
+- removed the old and deprecated "py.magic" namespace
- use apipkg-1.1 and make py.apipkg.initpkg|ApiModule available
- add py.iniconfig module for brain-dead easy ini-config file parsing
- introduce py.builtin.any()
--- a/doc/code.txt
+++ b/doc/code.txt
@@ -46,6 +46,11 @@ A quick example::
>>> str(c.source()).split('\n')[0]
"def read(self, mode='r'):"
+.. autoclass:: py.code.Code
+ :members:
+ :inherited-members:
+
+
``py.code.Source``
---------------------
@@ -67,6 +72,9 @@ Example::
>>> str(sub).strip() # XXX why is the strip() required?!?
'print "foo"'
+.. autoclass:: py.code.Source
+ :members:
+
``py.code.Traceback``
------------------------
@@ -92,6 +100,9 @@ Example::
>>> str(first.statement).strip().startswith('raise ValueError')
True
+.. autoclass:: py.code.Traceback
+ :members:
+
``py.code.Frame``
--------------------
@@ -111,6 +122,9 @@ Example (using the 'first' TracebackItem
>>> [namevalue[0] for namevalue in frame.getargs()]
['cls', 'path']
+.. autoclass:: py.code.Frame
+ :members:
+
``py.code.ExceptionInfo``
----------------------------
@@ -132,3 +146,6 @@ Example::
>>> excinfo.exconly()
"NameError: name 'foobar' is not defined"
+.. autoclass:: py.code.ExceptionInfo
+ :members:
+
--- /dev/null
+++ b/doc/conf.py
@@ -0,0 +1,262 @@
+# -*- coding: utf-8 -*-
+#
+# pylib documentation build configuration file, created by
+# sphinx-quickstart on Thu Oct 21 08:30:10 2010.
+#
+# This file is execfile()d with the current directory set to its containing dir.
+#
+# Note that not all possible configuration values are present in this
+# autogenerated file.
+#
+# All configuration values have a default; values that are commented out
+# serve to show the default.
+
+import sys, os
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#sys.path.insert(0, os.path.abspath('.'))
+
+# -- General configuration -----------------------------------------------------
+
+# If your documentation needs a minimal Sphinx version, state it here.
+#needs_sphinx = '1.0'
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', 'sphinx.ext.viewcode']
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# The suffix of source filenames.
+source_suffix = '.txt'
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = u'pylib'
+copyright = u'2010, holger krekel et. al.'
+
+# The version info for the project you're documenting, acts as replacement for
+# |version| and |release|, also used in various other places throughout the
+# built documents.
+#
+# The short X.Y version.
+version = '2.0'
+# The full version, including alpha/beta/rc tags.
+release = '2.0.0.dev0'
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#language = None
+
+# There are two options for replacing |today|: either, you set today to some
+# non-false value, then it is used:
+#today = ''
+# Else, today_fmt is used as the format for a strftime call.
+#today_fmt = '%B %d, %Y'
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+exclude_patterns = ['_build']
+
+# The reST default role (used for this markup: `text`) to use for all documents.
+#default_role = None
+
+# If true, '()' will be appended to :func: etc. cross-reference text.
+#add_function_parentheses = True
+
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+#add_module_names = True
+
+# If true, sectionauthor and moduleauthor directives will be shown in the
+# output. They are ignored by default.
+#show_authors = False
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# A list of ignored prefixes for module index sorting.
+#modindex_common_prefix = []
+
+
+# -- Options for HTML output ---------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages. See the documentation for
+# a list of builtin themes.
+html_theme = 'default'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further. For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents. If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar. Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+#html_logo = None
+
+# The name of an image file (within the static path) to use as favicon of the
+# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
+# pixels large.
+#html_favicon = None
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ['_static']
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it. The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'pylibdoc'
+
+
+# -- Options for LaTeX output --------------------------------------------------
+
+# The paper size ('letter' or 'a4').
+#latex_paper_size = 'letter'
+
+# The font size ('10pt', '11pt' or '12pt').
+#latex_font_size = '10pt'
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title, author, documentclass [howto/manual]).
+latex_documents = [
+ ('index', 'pylib.tex', u'pylib Documentation',
+ u'holger krekel et. al.', 'manual'),
+]
+
+# The name of an image file (relative to this directory) to place at the top of
+# the title page.
+#latex_logo = None
+
+# For "manual" documents, if this is true, then toplevel headings are parts,
+# not chapters.
+#latex_use_parts = False
+
+# If true, show page references after internal links.
+#latex_show_pagerefs = False
+
+# If true, show URL addresses after external links.
+#latex_show_urls = False
+
+# Additional stuff for the LaTeX preamble.
+#latex_preamble = ''
+
+# Documents to append as an appendix to all manuals.
+#latex_appendices = []
+
+# If false, no module index is generated.
+#latex_domain_indices = True
+
+
+# -- Options for manual page output --------------------------------------------
+
+# One entry per manual page. List of tuples
+# (source start file, name, description, authors, manual section).
+man_pages = [
+ ('index', 'pylib', u'pylib Documentation',
+ [u'holger krekel et. al.'], 1)
+]
+
+autodoc_member_order = "bysource"
+autodoc_default_flags = "inherited-members"
+
+# -- Options for Epub output ---------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = u'pylib'
+epub_author = u'holger krekel et. al.'
+epub_publisher = u'holger krekel et. al.'
+epub_copyright = u'2010, holger krekel et. al.'
+
+# The language of the text. It defaults to the language option
+# or en if the language is not set.
+#epub_language = ''
+
+# The scheme of the identifier. Typical schemes are ISBN or URL.
+#epub_scheme = ''
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#epub_identifier = ''
+
+# A unique identification for the text.
+#epub_uid = ''
+
+# HTML files that should be inserted before the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_pre_files = []
+
+# HTML files shat should be inserted after the pages created by sphinx.
+# The format is a list of tuples containing the path and title.
+#epub_post_files = []
+
+# A list of files that should not be packed into the epub file.
+#epub_exclude_files = []
+
+# The depth of the table of contents in toc.ncx.
+#epub_tocdepth = 3
+
+# Allow duplicate toc entries.
+#epub_tocdup = True
+
+
+# Example configuration for intersphinx: refer to the Python standard library.
+intersphinx_mapping = {'http://docs.python.org/': None}
--- a/doc/path.txt
+++ b/doc/path.txt
@@ -8,13 +8,13 @@ object to fs-like object trees (reading
files/directories, examining the types and structure, etc.), and out-of-the-box
provides a number of implementations of this API.
-Path implementations provided by ``py.path``
+py.test.local - local file system path
===============================================
.. _`local`:
-``py.path.local``
---------------------
+basic interactive example
+-------------------------------------
The first and most obvious of the implementations is a wrapper around a local
filesystem. It's just a bit nicer in usage than the regular Python APIs, and
@@ -40,8 +40,15 @@ a ``py.path.local`` object for us (which
>>> foofile.read(1)
'b'
+reference documentation
+---------------------------------
+
+.. autoclass:: py._path.local.LocalPath
+ :members:
+ :inherited-members:
+
``py.path.svnurl`` and ``py.path.svnwc``
-----------------------------------------------
+==================================================
Two other ``py.path`` implementations that the py lib provides wrap the
popular `Subversion`_ revision control system: the first (called 'svnurl')
@@ -78,8 +85,23 @@ Example usage of ``py.path.svnwc``:
.. _`Subversion`: http://subversion.tigris.org/
-Common vs. specific API
-=======================
+svn path related API reference
+-----------------------------------------
+
+.. autoclass:: py._path.svnwc.SvnWCCommandPath
+ :members:
+ :inherited-members:
+
+.. autoclass:: py._path.svnurl.SvnCommandPath
+ :members:
+ :inherited-members:
+
+.. autoclass:: py._path.svnwc.SvnAuth
+ :members:
+ :inherited-members:
+
+Common vs. specific API, Examples
+========================================
All Path objects support a common set of operations, suitable
for many use cases and allowing to transparently switch the
@@ -93,15 +115,12 @@ children, etc. Only things that are not
such as handling metadata (e.g. the Subversion "properties") require
using specific APIs.
-Examples
----------------------------------
-
A quick 'cookbook' of small examples that will be useful 'in real life',
which also presents parts of the 'common' API, and shows some non-common
methods:
Searching `.txt` files
-..........................
+--------------------------------
Search for a particular string inside all files with a .txt extension in a
specific directory.
@@ -123,7 +142,7 @@ specific directory.
['textfile1.txt', 'textfile2.txt', 'textfile2.txt']
Working with Paths
-.......................
+----------------------------
This example shows the ``py.path`` features to deal with
filesystem paths Note that the filesystem is never touched,
@@ -160,7 +179,7 @@ one, or a database or object tree, these
with their own notion of path seperators and dealing with conversions, etc.).
Checking path types
-.......................
+-------------------------------
Now we will show a bit about the powerful 'check()' method on paths, which
allows you to check whether a file exists, what type it is, etc.:
@@ -186,7 +205,7 @@ allows you to check whether a file exist
True
Setting svn-properties
-.......................
+--------------------------------
As an example of 'uncommon' methods, we'll show how to read and write
properties in an ``py.path.svnwc`` instance:
@@ -206,7 +225,7 @@ properties in an ``py.path.svnwc`` insta
0
SVN authentication
-.......................
+----------------------------
Some uncommon functionality can also be provided as extensions, such as SVN
authentication:
@@ -238,36 +257,4 @@ Known problems / limitations
there is no attention yet on making unicode paths
work or deal with the famous "8.3" filename issues.
-Future plans
-============
-The Subversion path implementations are based
-on the `svn` command line, not on the bindings.
-It makes sense now to directly use the bindings.
-
-Moreover, it would be good, also considering
-`execnet`_ distribution of programs, to
-be able to manipulate Windows Paths on Linux
-and vice versa. So we'd like to consider
-refactoring the path implementations
-to provide this choice (and getting rid
-of platform-dependencies as much as possible).
-
-There is some experimental small approach
-(``py/path/gateway/``) aiming at having
-a convenient Remote Path implementation.
-
-There are various hacks out there to have
-Memory-Filesystems and even path objects
-being directly mountable under Linux (via `fuse`).
-However, the Path object implementations
-do not internally have a clean abstraction
-of going to the filesystem - so with some
-refactoring it should become easier to
-have very custom Path objects, still offering
-the quite full interface without requiring
-to know about all details of the full path
-implementation.
-
-.. _`execnet`: execnet.html
-
--- /dev/null
+++ b/doc/links.inc
@@ -0,0 +1,16 @@
+
+.. _`skipping plugin`: plugin/skipping.html
+.. _`funcargs mechanism`: funcargs.html
+.. _`doctest.py`: http://docs.python.org/library/doctest.html
+.. _`xUnit style setup`: xunit_setup.html
+.. _`pytest_nose`: plugin/nose.html
+.. _`reStructured Text`: http://docutils.sourceforge.net
+.. _`Python debugger`: http://docs.python.org/lib/module-pdb.html
+.. _nose: http://somethingaboutorange.com/mrl/projects/nose/
+.. _pytest: http://pypi.python.org/pypi/pytest
+.. _mercurial: http://mercurial.selenic.com/wiki/
+.. _`setuptools`: http://pypi.python.org/pypi/setuptools
+.. _`distribute`: http://pypi.python.org/pypi/distribute
+.. _`pip`: http://pypi.python.org/pypi/pip
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
+.. _hudson: http://hudson-ci.org/
--- a/doc/conftest.py
+++ /dev/null
@@ -1,8 +0,0 @@
-#XXX make work: excludedirs = ['_build']
-import py
-pytest_plugins = ['pytest_restdoc']
-collect_ignore = ['test/attic.txt']
-
-def pytest_runtest_setup(item):
- if item.fspath.ext == ".txt":
- py.test.importorskip("pygments") # for raising an error
--- a/py/_path/local.py
+++ b/py/_path/local.py
@@ -203,14 +203,14 @@ class LocalPath(FSBase):
def new(self, **kw):
""" create a modified version of this path.
- the following keyword arguments modify various path parts:
+ the following keyword arguments modify various path parts::
a:/some/path/to/a/file.ext
- || drive
- |-------------| dirname
- |------| basename
- |--| purebasename
- |--| ext
+ xx drive
+ xxxxxxxxxxxxxxxxx dirname
+ xxxxxxxx basename
+ xxxx purebasename
+ xxx ext
"""
obj = object.__new__(self.__class__)
drive, dirname, basename, purebasename,ext = self._getbyspec(
@@ -461,8 +461,8 @@ class LocalPath(FSBase):
return self.strpath
def pypkgpath(self, pkgname=None):
- """ return the path's package path by looking for the given
- pkgname. If pkgname is None then look for the last
+ """ return the Python package path by looking for a
+ pkgname. If pkgname is None look for the last
directory upwards which still contains an __init__.py
and whose basename is python-importable.
Return None if a pkgpath can not be determined.
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -1,29 +1,37 @@
-py lib: tested useful cross-Python abstractions
-===============================================================
+.. pylib documentation master file, created by
+ sphinx-quickstart on Thu Oct 21 08:30:10 2010.
+ You can adapt this file completely to your liking, but it should at least
+ contain the root `toctree` directive.
-The ``py`` lib has several namespaces:
+Welcome to pylib's documentation!
+=================================
-`py.path`_: use path objects to transparently access local and svn filesystems.
+:ref:`2.0.0 release announcement <release-2.0.0>` and :ref:`CHANGELOG <changelog>`
-`py.code`_: generate code and use advanced introspection/traceback support.
+Contents:
-`py.io`_: Helper Classes for Capturing of Input/Output on FD/sys.std* level
+.. toctree::
-`py.xml`_ for generating in-memory xml/html object trees
+ install
+ path
+ code
+ io
+ log
+ xml
+ misc
-`py.log`_: an alpha document about the ad-hoc logging facilities
+ :maxdepth: 2
-`miscellaneous features`_ describes some small but nice py lib features.
+.. toctree::
+ :hidden:
-.. _`PyPI project page`: http://pypi.python.org/pypi/py/
+ announce/release-2.0.0
+ changelog
-For the latest Release, see `PyPI project page`_
+Indices and tables
+==================
-.. _`py-dev at codespeak net`: http://codespeak.net/mailman/listinfo/py-dev
-.. _`py.log`: log.html
-.. _`py.io`: io.html
-.. _`py.path`: path.html
-.. _`py.code`: code.html
-.. _`py.xml`: xml.html
-.. _`miscellaneous features`: misc.html
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--- a/testing/path/common.py
+++ b/testing/path/common.py
@@ -102,7 +102,8 @@ class CommonFSTests(object):
def test_fnmatch_file(self, path1):
assert path1.join("samplefile").check(fnmatch='s*e')
- assert path1.join("samplefile").check(notfnmatch='s*x')
+ assert path1.join("samplefile").fnmatch('s*e')
+ assert not path1.join("samplefile").fnmatch('s*x')
assert not path1.join("samplefile").check(fnmatch='s*x')
#def test_fnmatch_dir(self, path1):
--- a/setup.py
+++ b/setup.py
@@ -9,8 +9,6 @@ pylib: cross-python development utils
py.path.local: local path objects
py.path.svnwc: local subversion WC paths
-py.iniconfig: parse for .ini / .cfg files
-py.apipkg: package API export control + lazy import
py.io: io-capturing on filedescriptor or sys.* level
Platforms: Linux, Win32, OSX
--- a/doc/xml.txt
+++ b/doc/xml.txt
@@ -1,8 +1,7 @@
====================================================
-py.xml: Lightweight and flexible xml/html generation
+py.xml: simple pythonic xml/html file generation
====================================================
-
Motivation
==========
@@ -11,9 +10,6 @@ xml and html trees. However, many of th
steep learning curve and are often hard to debug. Not to
speak of the fact that they are frameworks to begin with.
-The py lib strives to offer enough functionality to represent
-itself and especially its API in html or xml.
-
.. _xist: http://www.livinglogic.de/Python/xist/index.html
a pythonic object model , please
--- a/.hgignore
+++ b/.hgignore
@@ -15,6 +15,7 @@ syntax:glob
*.orig
*~
+doc/_build
build/
dist/
*.egg-info
--- a/doc/confrest.py
+++ /dev/null
@@ -1,289 +0,0 @@
-import py
-
-from pytest.plugin.restdoc import convert_rest_html, strip_html_header
-
-html = py.xml.html
-
-class css:
- #pagetitle = "pagetitle"
- contentspace = "contentspace"
- menubar = "menubar"
- navspace = "navspace"
- versioninfo = "versioninfo"
-
-class Page(object):
- doctype = ('<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"'
- ' "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">\n')
- googlefragment = """
-<script type="text/javascript">
-var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
-document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
-</script>
-<script type="text/javascript">
-try {
-var pageTracker = _gat._getTracker("UA-7597274-3");
-pageTracker._trackPageview();
-} catch(err) {}</script>
-"""
-
- def __init__(self, project, title, targetpath, stylesheeturl=None,
- type="text/html", encoding="ISO-8859-1"):
- self.project = project
- self.title = project.prefix_title + title
- self.targetpath = targetpath
- self.stylesheeturl = stylesheeturl
- self.type = type
- self.encoding = encoding
-
- self.body = html.body()
- self.head = html.head()
- self._root = html.html(self.head, self.body)
- self.fill()
-
- def a_href(self, name, url, **kwargs):
- return html.a(name, class_="menu", href=url, **kwargs)
-
- def a_docref(self, name, relhtmlpath):
- docpath = self.project.docpath
- return html.div(html.a(name, class_="menu",
- href=relpath(self.targetpath.strpath,
- docpath.join(relhtmlpath).strpath)))
-
- def a_apigenref(self, name, relhtmlpath):
- apipath = self.project.apigenpath
- return html.a(name, class_="menu",
- href=relpath(self.targetpath.strpath,
- apipath.join(relhtmlpath).strpath))
-
- def fill_menubar(self):
- items = [
- self.a_docref("INSTALL", "install.html"),
- self.a_docref("CONTACT", "contact.html"),
- self.a_docref("CHANGELOG", "changelog.html"),
- self.a_docref("FAQ", "faq.html"),
- html.div(
- html.h3("py.test:"),
- self.a_docref("Index", "test/index.html"),
- self.a_docref("Quickstart", "test/quickstart.html"),
- self.a_docref("Features", "test/features.html"),
- self.a_docref("Funcargs", "test/funcargs.html"),
- self.a_docref("Plugins", "test/plugin/index.html"),
- self.a_docref("Customize", "test/customize.html"),
- self.a_docref("Tutorials", "test/talks.html"),
- self.a_href("hudson-tests", "http://hudson.testrun.org")
- ),
- html.div(
- html.h3("supporting APIs:"),
- self.a_docref("Index", "index.html"),
- self.a_docref("py.path", "path.html"),
- self.a_docref("py.code", "code.html"),
- )
- #self.a_docref("py.code", "code.html"),
- #self.a_apigenref("api", "api/index.html"),
- #self.a_apigenref("source", "source/index.html"),
- #self.a_href("source", "http://bitbucket.org/hpk42/py-trunk/src/"),
- ]
- self.menubar = html.div(id=css.menubar, *[
- html.div(item) for item in items])
- version = py.version
- announcelink = self.a_docref("%s ANN" % version,
- "announce/release-%s.html" %(version,))
- self.menubar.insert(0,
- html.div(announcelink))
- #self.a_href("%s-%s" % (self.title, py.version),
- # "http://pypi.python.org/pypi/py/%s" % version,
- #id="versioninfo",
-
- def fill(self):
- content_type = "%s;charset=%s" %(self.type, self.encoding)
- self.head.append(html.title(self.title))
- self.head.append(html.meta(name="Content-Type", content=content_type))
- if self.stylesheeturl:
- self.head.append(
- html.link(href=self.stylesheeturl,
- media="screen", rel="stylesheet",
- type="text/css"))
- self.fill_menubar()
-
- self.body.append(html.div(
- self.project.logo,
- self.menubar,
- id=css.navspace,
- ))
-
- #self.body.append(html.div(self.title, id=css.pagetitle))
- self.contentspace = html.div(id=css.contentspace)
- self.body.append(self.contentspace)
-
- def unicode(self, doctype=True):
- page = self._root.unicode()
- page = page.replace("</body>", self.googlefragment + "</body>")
- if doctype:
- return self.doctype + page
- else:
- return page
-
-class PyPage(Page):
- def get_menubar(self):
- menubar = super(PyPage, self).get_menubar()
- # base layout
- menubar.append(
- html.a("issue", href="https://codespeak.net/issue/py-dev/",
- class_="menu"),
- )
- return menubar
-
-
-def getrealname(username):
- try:
- import uconf
- except ImportError:
- return username
- try:
- user = uconf.system.User(username)
- except KeyboardInterrupt:
- raise
- try:
- return user.realname or username
- except KeyError:
- return username
-
-
-class Project:
- mydir = py.path.local(__file__).dirpath()
- title = "py lib"
- prefix_title = "" # we have a logo already containing "py lib"
- encoding = 'latin1'
- logo = html.div(
- html.a(
- html.img(alt="py lib", id='pyimg', height=114/2, width=154/2,
- src="http://codespeak.net/img/pylib.png"),
- href="http://pylib.org"))
- Page = PyPage
-
- def __init__(self, sourcepath=None):
- if sourcepath is None:
- sourcepath = self.mydir
- self.setpath(sourcepath)
-
- def setpath(self, sourcepath, docpath=None,
- apigenpath=None, stylesheet=None):
- self.sourcepath = sourcepath
- if docpath is None:
- docpath = sourcepath
- self.docpath = docpath
- if apigenpath is None:
- apigenpath = docpath
- self.apigenpath = apigenpath
- if stylesheet is None:
- p = sourcepath.join("style.css")
- if p.check():
- self.stylesheet = p
- else:
- self.stylesheet = None
- else:
- p = sourcepath.join(stylesheet)
- if p.check():
- stylesheet = p
- self.stylesheet = stylesheet
- #assert self.stylesheet
- self.apigen_relpath = relpath(
- self.docpath.strpath + '/', self.apigenpath.strpath + '/')
-
- def get_content(self, txtpath, encoding):
- return unicode(txtpath.read(), encoding)
-
- def get_htmloutputpath(self, txtpath):
- reloutputpath = txtpath.new(ext='.html').relto(self.sourcepath)
- return self.docpath.join(reloutputpath)
-
- def process(self, txtpath):
- encoding = self.encoding
- content = self.get_content(txtpath, encoding)
- outputpath = self.get_htmloutputpath(txtpath)
-
- stylesheet = self.stylesheet
- if isinstance(stylesheet, py.path.local):
- if not self.docpath.join(stylesheet.basename).check():
- docpath.ensure(dir=True)
- stylesheet.copy(docpath)
- stylesheet = relpath(outputpath.strpath,
- self.docpath.join(stylesheet.basename).strpath)
-
- content = convert_rest_html(content, txtpath,
- stylesheet=stylesheet, encoding=encoding)
- content = strip_html_header(content, encoding=encoding)
-
- title = txtpath.purebasename
- if txtpath.dirpath().basename == "test":
- title = "py.test " + title
- # title = "[%s] %s" % (txtpath.purebasename, py.version)
- page = self.Page(self, title,
- outputpath, stylesheeturl=stylesheet)
-
- try:
- modified = py.process.cmdexec(
- "hg tip --template 'modified {date|shortdate}'"
- )
- except py.process.cmdexec.Error:
- modified = " "
-
- #page.body.append(html.div(modified, id="docinfoline"))
-
- page.contentspace.append(py.xml.raw(content))
- outputpath.ensure().write(page.unicode().encode(encoding))
-
-# XXX this function comes from apigen/linker.py, put it
-# somewhere in py lib
-import os
-def relpath(p1, p2, sep=os.path.sep, back='..', normalize=True):
- """ create a relative path from p1 to p2
-
- sep is the seperator used for input and (depending
- on the setting of 'normalize', see below) output
-
- back is the string used to indicate the parent directory
-
- when 'normalize' is True, any backslashes (\) in the path
- will be replaced with forward slashes, resulting in a consistent
- output on Windows and the rest of the world
-
- paths to directories must end on a / (URL style)
- """
- if normalize:
- p1 = p1.replace(sep, '/')
- p2 = p2.replace(sep, '/')
- sep = '/'
- # XXX would be cool to be able to do long filename
- # expansion and drive
- # letter fixes here, and such... iow: windows sucks :(
- if (p1.startswith(sep) ^ p2.startswith(sep)):
- raise ValueError("mixed absolute relative path: %r -> %r" %(p1, p2))
- fromlist = p1.split(sep)
- tolist = p2.split(sep)
-
- # AA
- # AA BB -> AA/BB
- #
- # AA BB
- # AA CC -> CC
- #
- # AA BB
- # AA -> ../AA
-
- diffindex = 0
- for x1, x2 in zip(fromlist, tolist):
- if x1 != x2:
- break
- diffindex += 1
- commonindex = diffindex - 1
-
- fromlist_diff = fromlist[diffindex:]
- tolist_diff = tolist[diffindex:]
-
- if not fromlist_diff:
- return sep.join(tolist[commonindex:])
- backcount = len(fromlist_diff)
- if tolist_diff:
- return sep.join([back,]*(backcount-1) + tolist_diff)
- return sep.join([back,]*(backcount) + tolist[commonindex:])
--- a/doc/changelog.txt
+++ b/doc/changelog.txt
@@ -1,2 +1,3 @@
+.. _`changelog`:
.. include:: ../CHANGELOG
--- a/doc/contact.txt
+++ /dev/null
@@ -1,30 +0,0 @@
-Contact and Communication points
-===================================
-
-- `py-dev developers list`_ announcements and discussions.
-
-- #pylib on irc.freenode.net IRC channel for random questions.
-
-- `tetamap`_: Holger Krekel's blog, main author of pylib code.
-
-- `commit mailing list`_ or `@pylibcommit`_ to follow development commits,
-
-- `bitbucket issue tracker`_ use this bitbucket issue tracker to report
- bugs or request features.
-
-.. _`bitbucket issue tracker`: http://bitbucket.org/hpk42/pylib/issues/
-
-.. _`get an account`:
-
-.. _tetamap: http://tetamap.wordpress.com
-
-.. _`@pylibcommit`: http://twitter.com/pylibcommit
-
-
-.. _codespeak: http://codespeak.net/
-.. _`py-dev`:
-.. _`development mailing list`:
-.. _`py-dev developers list`: http://codespeak.net/mailman/listinfo/py-dev
-.. _`py-svn`:
-.. _`commit mailing list`: http://codespeak.net/mailman/listinfo/py-svn
-
--- /dev/null
+++ b/doc/announce/release-2.0.0.txt
@@ -0,0 +1,23 @@
+
+.. _`release-2.0.0`:
+
+pylib 2.0.0: cross-platform library for path, code, io, ... manipulations
+===========================================================================
+
+"pylib" is a library comprising APIs for filesystem and svn path manipulations,
+dynamic code construction, IO capturing and a Python2/Python3 compatibility
+namespace. It runs unmodified on all Python interpreters compatible to
+Python2.4 up until Python 3.2. "pylib" functionality used to be contained in a
+PyPI distribution named "py" and then contained "py.test" and other
+command line tools. This is now history. "pytest" is its own distribution
+and "pylib" can be and is used completely separately from py.test.
+The other "py.*" command line tools are installed with the new
+separate "pycmd" distribution.
+
+The general idea for "pylib" is to place high value on providing
+some basic APIs that are continously tested against many Python
+interpreters and thus also to help transition.
+
+cheers,
+holger
+
More information about the pytest-commit
mailing list