diff options
Diffstat (limited to 'testing/web-platform/tests/tools/py/doc')
37 files changed, 4842 insertions, 0 deletions
diff --git a/testing/web-platform/tests/tools/py/doc/Makefile b/testing/web-platform/tests/tools/py/doc/Makefile new file mode 100644 index 000000000..0a0e89e01 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/Makefile @@ -0,0 +1,133 @@ +# 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)/* + +install: clean html + rsync -avz _build/html/ code:www-pylib/ + +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/py.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/py.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/py" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/py" + @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." diff --git a/testing/web-platform/tests/tools/py/doc/_templates/layout.html b/testing/web-platform/tests/tools/py/doc/_templates/layout.html new file mode 100644 index 000000000..683863aa4 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/_templates/layout.html @@ -0,0 +1,18 @@ +{% extends "!layout.html" %} + +{% block footer %} +{{ super() }} +<script type="text/javascript"> + + var _gaq = _gaq || []; + _gaq.push(['_setAccount', 'UA-7597274-14']); + _gaq.push(['_trackPageview']); + + (function() { + var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; + ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; + var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); + })(); + +</script> +{% endblock %} diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-0.9.0.txt b/testing/web-platform/tests/tools/py/doc/announce/release-0.9.0.txt new file mode 100644 index 000000000..071093135 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-0.9.0.txt @@ -0,0 +1,7 @@ +py lib 1.0.0: XXX +====================================================================== + +Welcome to the 1.0.0 py lib release - a library aiming to +support agile and test-driven python development on various levels. + +XXX diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-0.9.2.txt b/testing/web-platform/tests/tools/py/doc/announce/release-0.9.2.txt new file mode 100644 index 000000000..bc2d2ef29 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-0.9.2.txt @@ -0,0 +1,27 @@ +py lib 0.9.2: bugfix release +============================= + +Welcome to the 0.9.2 py lib and py.test release - +mainly fixing Windows issues, providing better +packaging and integration with setuptools. + +Here is a quick summary of what the py lib provides: + +* py.test: cross-project testing tool with many advanced features +* py.execnet: ad-hoc code distribution to SSH, Socket and local sub processes +* py.magic.greenlet: micro-threads on standard CPython ("stackless-light") +* py.path: path abstractions over local and subversion files +* rich documentation of py's exported API +* tested against Linux, Win32, OSX, works on python 2.3-2.6 + +See here for more information: + +Pypi pages: http://pypi.python.org/pypi/py/ + +Download/Install: http://codespeak.net/py/0.9.2/download.html + +Documentation/API: http://codespeak.net/py/0.9.2/index.html + +best and have fun, + +holger krekel diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.0.0.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.0.0.txt new file mode 100644 index 000000000..7024255a1 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.0.0.txt @@ -0,0 +1,63 @@ + +pylib 1.0.0 released: testing-with-python innovations continue +-------------------------------------------------------------------- + +Took a few betas but finally i uploaded a `1.0.0 py lib release`_, +featuring the mature and powerful py.test tool and "execnet-style" +*elastic* distributed programming. With the new release, there are +many new advanced automated testing features - here is a quick summary: + +* funcargs_ - pythonic zero-boilerplate fixtures for Python test functions : + + - totally separates test code, test configuration and test setup + - ideal for integration and functional tests + - allows for flexible and natural test parametrization schemes + +* new `plugin architecture`_, allowing easy-to-write project-specific and cross-project single-file plugins. The most notable new external plugin is `oejskit`_ which naturally enables **running and reporting of javascript-unittests in real-life browsers**. + +* many new features done in easy-to-improve `default plugins`_, highlights: + + * xfail: mark tests as "expected to fail" and report separately. + * pastebin: automatically send tracebacks to pocoo paste service + * capture: flexibly capture stdout/stderr of subprocesses, per-test ... + * monkeypatch: safely monkeypatch modules/classes from within tests + * unittest: run and integrate traditional unittest.py tests + * figleaf: generate html coverage reports with the figleaf module + * resultlog: generate buildbot-friendly reporting output + * ... + +* `distributed testing`_ and `elastic distributed execution`_: + + - new unified "TX" URL scheme for specifying remote processes + - new distribution modes "--dist=each" and "--dist=load" + - new sync/async ways to handle 1:N communication + - improved documentation + +The py lib continues to offer most of the functionality used by +the testing tool in `independent namespaces`_. + +Some non-test related code, notably greenlets/co-routines and +api-generation now live as their own projects which simplifies the +installation procedure because no C-Extensions are required anymore. + +The whole package should work well with Linux, Win32 and OSX, on Python +2.3, 2.4, 2.5 and 2.6. (Expect Python3 compatibility soon!) + +For more info, see the py.test and py lib documentation: + + http://pytest.org + + http://pylib.org + +have fun, +holger + +.. _`independent namespaces`: http://pylib.org +.. _`funcargs`: http://codespeak.net/py/dist/test/funcargs.html +.. _`plugin architecture`: http://codespeak.net/py/dist/test/extend.html +.. _`default plugins`: http://codespeak.net/py/dist/test/plugin/index.html +.. _`distributed testing`: http://codespeak.net/py/dist/test/dist.html +.. _`elastic distributed execution`: http://codespeak.net/py/dist/execnet.html +.. _`1.0.0 py lib release`: http://pypi.python.org/pypi/py +.. _`oejskit`: http://codespeak.net/py/dist/test/plugin/oejskit.html + diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.0.1.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.0.1.txt new file mode 100644 index 000000000..0c9f8760b --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.0.1.txt @@ -0,0 +1,48 @@ +1.0.1: improved reporting, nose/unittest.py support, bug fixes +----------------------------------------------------------------------- + +This is a bugfix release of pylib/py.test also coming with: + +* improved documentation, improved navigation +* test failure reporting improvements +* support for directly running existing nose/unittest.py style tests + +visit here for more info, including quickstart and tutorials: + + http://pytest.org and http://pylib.org + + +Changelog 1.0.0 to 1.0.1 +------------------------ + +* added a default 'pytest_nose' plugin which handles nose.SkipTest, + nose-style function/method/generator setup/teardown and + tries to report functions correctly. + +* improved documentation, better navigation: see http://pytest.org + +* added a "--help-config" option to show conftest.py / ENV-var names for + all longopt cmdline options, and some special conftest.py variables. + renamed 'conf_capture' conftest setting to 'option_capture' accordingly. + +* unicode fixes: capturing and unicode writes to sys.stdout + (through e.g a print statement) now work within tests, + they are encoded as "utf8" by default, also terminalwriting + was adapted and somewhat unified between windows and linux + +* fix issue #27: better reporting on non-collectable items given on commandline + (e.g. pyc files) + +* fix issue #33: added --version flag (thanks Benjamin Peterson) + +* fix issue #32: adding support for "incomplete" paths to wcpath.status() + +* "Test" prefixed classes are *not* collected by default anymore if they + have an __init__ method + +* monkeypatch setenv() now accepts a "prepend" parameter + +* improved reporting of collection error tracebacks + +* simplified multicall mechanism and plugin architecture, + renamed some internal methods and argnames diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.0.2.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.0.2.txt new file mode 100644 index 000000000..235461953 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.0.2.txt @@ -0,0 +1,5 @@ +1.0.2: packaging fixes +----------------------------------------------------------------------- + +this release is purely a release for fixing packaging issues. + diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.1.0.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.1.0.txt new file mode 100644 index 000000000..0441c3215 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.1.0.txt @@ -0,0 +1,115 @@ +py.test/pylib 1.1.0: Python3, Jython, advanced skipping, cleanups ... +-------------------------------------------------------------------------------- + +Features: + +* compatible to Python3 (single py2/py3 source), `easy to install`_ +* conditional skipping_: skip/xfail based on platform/dependencies +* generalized marking_: mark tests one a whole-class or whole-module basis + +Fixes: + +* code reduction and "de-magification" (e.g. 23 KLoc -> 11 KLOC) +* distribute testing requires the now separately released execnet_ package +* funcarg-setup/caching, "same-name" test modules now cause an exlicit error +* de-cluttered reporting options, --report for skipped/xfail details + +Compatibilities + +1.1.0 should allow running test code that already worked well with 1.0.2 +plus some more due to improved unittest/nose compatibility. + +More information: http://pytest.org + +thanks and have fun, + +holger (http://twitter.com/hpk42) + +.. _execnet: http://codespeak.net/execnet +.. _`easy to install`: ../install.html +.. _marking: ../test/plugin/mark.html +.. _skipping: ../test/plugin/skipping.html + + +Changelog 1.0.2 -> 1.1.0 +----------------------------------------------------------------------- + +* remove py.rest tool and internal namespace - it was + never really advertised and can still be used with + the old release if needed. If there is interest + it could be revived into its own tool i guess. + +* fix issue48 and issue59: raise an Error if the module + from an imported test file does not seem to come from + the filepath - avoids "same-name" confusion that has + been reported repeatedly + +* merged Ronny's nose-compatibility hacks: now + nose-style setup_module() and setup() functions are + supported + +* introduce generalized py.test.mark function marking + +* reshuffle / refine command line grouping + +* deprecate parser.addgroup in favour of getgroup which creates option group + +* add --report command line option that allows to control showing of skipped/xfailed sections + +* generalized skipping: a new way to mark python functions with skipif or xfail + at function, class and modules level based on platform or sys-module attributes. + +* extend py.test.mark decorator to allow for positional args + +* introduce and test "py.cleanup -d" to remove empty directories + +* fix issue #59 - robustify unittest test collection + +* make bpython/help interaction work by adding an __all__ attribute + to ApiModule, cleanup initpkg + +* use MIT license for pylib, add some contributors + +* remove py.execnet code and substitute all usages with 'execnet' proper + +* fix issue50 - cached_setup now caches more to expectations + for test functions with multiple arguments. + +* merge Jarko's fixes, issue #45 and #46 + +* add the ability to specify a path for py.lookup to search in + +* fix a funcarg cached_setup bug probably only occuring + in distributed testing and "module" scope with teardown. + +* many fixes and changes for making the code base python3 compatible, + many thanks to Benjamin Peterson for helping with this. + +* consolidate builtins implementation to be compatible with >=2.3, + add helpers to ease keeping 2 and 3k compatible code + +* deprecate py.compat.doctest|subprocess|textwrap|optparse + +* deprecate py.magic.autopath, remove py/magic directory + +* move pytest assertion handling to py/code and a pytest_assertion + plugin, add "--no-assert" option, deprecate py.magic namespaces + in favour of (less) py.code ones. + +* consolidate and cleanup py/code classes and files + +* cleanup py/misc, move tests to bin-for-dist + +* introduce delattr/delitem/delenv methods to py.test's monkeypatch funcarg + +* consolidate py.log implementation, remove old approach. + +* introduce py.io.TextIO and py.io.BytesIO for distinguishing between + text/unicode and byte-streams (uses underlying standard lib io.* + if available) + +* make py.unittest_convert helper script available which converts "unittest.py" + style files into the simpler assert/direct-test-classes py.test/nosetests + style. The script was written by Laura Creighton. + +* simplified internal localpath implementation diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.1.1.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.1.1.txt new file mode 100644 index 000000000..83e6a1fd8 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.1.1.txt @@ -0,0 +1,48 @@ +py.test/pylib 1.1.1: bugfix release, setuptools plugin registration +-------------------------------------------------------------------------------- + +This is a compatibility fixing release of pylib/py.test to work +better with previous 1.0.x test code bases. It also contains fixes +and changes to work with `execnet>=1.0.0`_ to provide distributed +testing and looponfailing testing modes. py-1.1.1 also introduces +a new mechanism for registering plugins via setuptools. + +What is pylib/py.test? +----------------------- + +py.test is an advanced automated testing tool working with +Python2, Python3 and Jython versions on all major operating +systems. It has an extensive plugin architecture and can run many +existing common Python test suites without modification. Moreover, +it offers some unique features not found in other +testing tools. See http://pytest.org for more info. + +The pylib also contains a localpath and svnpath implementation +and some developer-oriented command line tools. See +http://pylib.org for more info. + +thanks to all who helped and gave feedback, +have fun, + +holger (http://twitter.com/hpk42) + +.. _`execnet>=1.0.0`: http://codespeak.net/execnet + +Changes between 1.1.1 and 1.1.0 +===================================== + +- introduce automatic plugin registration via 'pytest11' + entrypoints via setuptools' pkg_resources.iter_entry_points + +- fix py.test dist-testing to work with execnet >= 1.0.0b4 + +- re-introduce py.test.cmdline.main() for better backward compatibility + +- svn paths: fix a bug with path.check(versioned=True) for svn paths, + allow '%' in svn paths, make svnwc.update() default to interactive mode + like in 1.0.x and add svnwc.update(interactive=False) to inhibit interaction. + +- refine distributed tarball to contain test and no pyc files + +- try harder to have deprecation warnings for py.compat.* accesses + report a correct location diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.2.0.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.2.0.txt new file mode 100644 index 000000000..4f6a56144 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.2.0.txt @@ -0,0 +1,116 @@ +py.test/pylib 1.2.0: junitxml, standalone test scripts, pluginization +-------------------------------------------------------------------------------- + +py.test is an advanced automated testing tool working with +Python2, Python3 and Jython versions on all major operating +systems. It has a simple plugin architecture and can run many +existing common Python test suites without modification. It offers +some unique features not found in other testing tools. +See http://pytest.org for more info. + +py.test 1.2.0 brings many bug fixes and interesting new abilities: + +* --junitxml=path will create an XML file for use with CI processing +* --genscript=path creates a standalone py.test-equivalent test-script +* --ignore=path prevents collection of anything below that path +* --confcutdir=path only lookup conftest.py test configs below that path +* a 'pytest_report_header' hook to add info to the terminal report header +* a 'pytestconfig' function argument gives direct access to option values +* 'pytest_generate_tests' can now be put into a class as well +* on CPython py.test additionally installs as "py.test-VERSION", on + Jython as py.test-jython and on PyPy as py.test-pypy-XYZ + +Apart from many bug fixes 1.2.0 also has better pluginization: +Distributed testing and looponfailing testing now live in the +separately installable 'pytest-xdist' plugin. The same is true for +'pytest-figleaf' for doing coverage reporting. Those two plugins +can serve well now as blue prints for doing your own. + +thanks to all who helped and gave feedback, +have fun, + +holger krekel, January 2010 + +Changes between 1.2.0 and 1.1.1 +===================================== + +- moved dist/looponfailing from py.test core into a new + separately released pytest-xdist plugin. + +- new junitxml plugin: --junitxml=path will generate a junit style xml file + which is processable e.g. by the Hudson CI system. + +- new option: --genscript=path will generate a standalone py.test script + which will not need any libraries installed. thanks to Ralf Schmitt. + +- new option: --ignore will prevent specified path from collection. + Can be specified multiple times. + +- new option: --confcutdir=dir will make py.test only consider conftest + files that are relative to the specified dir. + +- new funcarg: "pytestconfig" is the pytest config object for access + to command line args and can now be easily used in a test. + +- install 'py.test' and `py.which` with a ``-$VERSION`` suffix to + disambiguate between Python3, python2.X, Jython and PyPy installed versions. + +- new "pytestconfig" funcarg allows access to test config object + +- new "pytest_report_header" hook can return additional lines + to be displayed at the header of a test run. + +- (experimental) allow "py.test path::name1::name2::..." for pointing + to a test within a test collection directly. This might eventually + evolve as a full substitute to "-k" specifications. + +- streamlined plugin loading: order is now as documented in + customize.html: setuptools, ENV, commandline, conftest. + also setuptools entry point names are turned to canonical namees ("pytest_*") + +- automatically skip tests that need 'capfd' but have no os.dup + +- allow pytest_generate_tests to be defined in classes as well + +- deprecate usage of 'disabled' attribute in favour of pytestmark +- deprecate definition of Directory, Module, Class and Function nodes + in conftest.py files. Use pytest collect hooks instead. + +- collection/item node specific runtest/collect hooks are only called exactly + on matching conftest.py files, i.e. ones which are exactly below + the filesystem path of an item + +- change: the first pytest_collect_directory hook to return something + will now prevent further hooks to be called. + +- change: figleaf plugin now requires --figleaf to run. Also + change its long command line options to be a bit shorter (see py.test -h). + +- change: pytest doctest plugin is now enabled by default and has a + new option --doctest-glob to set a pattern for file matches. + +- change: remove internal py._* helper vars, only keep py._pydir + +- robustify capturing to survive if custom pytest_runtest_setup + code failed and prevented the capturing setup code from running. + +- make py.test.* helpers provided by default plugins visible early - + works transparently both for pydoc and for interactive sessions + which will regularly see e.g. py.test.mark and py.test.importorskip. + +- simplify internal plugin manager machinery +- simplify internal collection tree by introducing a RootCollector node + +- fix assert reinterpreation that sees a call containing "keyword=..." + +- fix issue66: invoke pytest_sessionstart and pytest_sessionfinish + hooks on slaves during dist-testing, report module/session teardown + hooks correctly. + +- fix issue65: properly handle dist-testing if no + execnet/py lib installed remotely. + +- skip some install-tests if no execnet is available + +- fix docs, fix internal bin/ script generation + diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.2.1.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.2.1.txt new file mode 100644 index 000000000..5bf8ba22d --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.2.1.txt @@ -0,0 +1,66 @@ +py.test/pylib 1.2.1: little fixes and improvements +-------------------------------------------------------------------------------- + +py.test is an advanced automated testing tool working with +Python2, Python3 and Jython versions on all major operating +systems. It has a simple plugin architecture and can run many +existing common Python test suites without modification. It offers +some unique features not found in other testing tools. +See http://pytest.org for more info. + +py.test 1.2.1 brings bug fixes and some new options and abilities triggered +by user feedback: + +* --funcargs [testpath] will show available builtin- and project funcargs. +* display a short and concise traceback if funcarg lookup fails. +* early-load "conftest.py" files in non-dot first-level sub directories. +* --tb=line will print a single line for each failing test (issue67) +* py.cleanup has a number of new options, cleanups up setup.py related files +* fix issue78: always call python-level teardown functions even if the + according setup failed. + +For more detailed information see the changelog below. + +cheers and have fun, + +holger + + +Changes between 1.2.1 and 1.2.0 +===================================== + +- refined usage and options for "py.cleanup":: + + py.cleanup # remove "*.pyc" and "*$py.class" (jython) files + py.cleanup -e .swp -e .cache # also remove files with these extensions + py.cleanup -s # remove "build" and "dist" directory next to setup.py files + py.cleanup -d # also remove empty directories + py.cleanup -a # synonym for "-s -d -e 'pip-log.txt'" + py.cleanup -n # dry run, only show what would be removed + +- add a new option "py.test --funcargs" which shows available funcargs + and their help strings (docstrings on their respective factory function) + for a given test path + +- display a short and concise traceback if a funcarg lookup fails + +- early-load "conftest.py" files in non-dot first-level sub directories. + allows to conveniently keep and access test-related options in a ``test`` + subdir and still add command line options. + +- fix issue67: new super-short traceback-printing option: "--tb=line" will print a single line for each failing (python) test indicating its filename, lineno and the failure value + +- fix issue78: always call python-level teardown functions even if the + according setup failed. This includes refinements for calling setup_module/class functions + which will now only be called once instead of the previous behaviour where they'd be called + multiple times if they raise an exception (including a Skipped exception). Any exception + will be re-corded and associated with all tests in the according module/class scope. + +- fix issue63: assume <40 columns to be a bogus terminal width, default to 80 + +- fix pdb debugging to be in the correct frame on raises-related errors + +- update apipkg.py to fix an issue where recursive imports might + unnecessarily break importing + +- fix plugin links diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.3.0.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.0.txt new file mode 100644 index 000000000..cf97db036 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.0.txt @@ -0,0 +1,580 @@ +py.test/pylib 1.3.0: new options, per-plugin hooks, fixes ... +=========================================================================== + +The 1.3.0 release introduces new options, bug fixes and improved compatibility +with Python3 and Jython-2.5.1 on Windows. If you already use py-1.2 chances +are you can use py-1.3.0. See the below CHANGELOG for more details and +http://pylib.org/install.html for installation instructions. + +py.test is an advanced automated testing tool working with Python2, +Python3, Jython and PyPy versions on all major operating systems. It +offers a no-boilerplate testing approach and has inspired other testing +tools and enhancements in the standard Python library for more than five +years. It has a simple and extensive plugin architecture, configurable +reporting and provides unique ways to make it fit to your testing +process and needs. + +See http://pytest.org for more info. + +cheers and have fun, + +holger krekel + +Changes between 1.2.1 and 1.3.0 +================================================== + +- deprecate --report option in favour of a new shorter and easier to + remember -r option: it takes a string argument consisting of any + combination of 'xfsX' characters. They relate to the single chars + you see during the dotted progress printing and will print an extra line + per test at the end of the test run. This extra line indicates the exact + position or test ID that you directly paste to the py.test cmdline in order + to re-run a particular test. + +- allow external plugins to register new hooks via the new + pytest_addhooks(pluginmanager) hook. The new release of + the pytest-xdist plugin for distributed and looponfailing + testing requires this feature. + +- add a new pytest_ignore_collect(path, config) hook to allow projects and + plugins to define exclusion behaviour for their directory structure - + for example you may define in a conftest.py this method:: + + def pytest_ignore_collect(path): + return path.check(link=1) + + to prevent even collection of any tests in symlinked dirs. + +- new pytest_pycollect_makemodule(path, parent) hook for + allowing customization of the Module collection object for a + matching test module. + +- extend and refine xfail mechanism:: + + @py.test.mark.xfail(run=False) do not run the decorated test + @py.test.mark.xfail(reason="...") prints the reason string in xfail summaries + + specifiying ``--runxfail`` on command line ignores xfail markers to show + you the underlying traceback. + +- expose (previously internal) commonly useful methods: + py.io.get_terminal_with() -> return terminal width + py.io.ansi_print(...) -> print colored/bold text on linux/win32 + py.io.saferepr(obj) -> return limited representation string + +- expose test outcome related exceptions as py.test.skip.Exception, + py.test.raises.Exception etc., useful mostly for plugins + doing special outcome interpretation/tweaking + +- (issue85) fix junitxml plugin to handle tests with non-ascii output + +- fix/refine python3 compatibility (thanks Benjamin Peterson) + +- fixes for making the jython/win32 combination work, note however: + jython2.5.1/win32 does not provide a command line launcher, see + http://bugs.jython.org/issue1491 . See pylib install documentation + for how to work around. + +- fixes for handling of unicode exception values and unprintable objects + +- (issue87) fix unboundlocal error in assertionold code + +- (issue86) improve documentation for looponfailing + +- refine IO capturing: stdin-redirect pseudo-file now has a NOP close() method + +- ship distribute_setup.py version 0.6.10 + +- added links to the new capturelog and coverage plugins + + +Changes between 1.2.1 and 1.2.0 +===================================== + +- refined usage and options for "py.cleanup":: + + py.cleanup # remove "*.pyc" and "*$py.class" (jython) files + py.cleanup -e .swp -e .cache # also remove files with these extensions + py.cleanup -s # remove "build" and "dist" directory next to setup.py files + py.cleanup -d # also remove empty directories + py.cleanup -a # synonym for "-s -d -e 'pip-log.txt'" + py.cleanup -n # dry run, only show what would be removed + +- add a new option "py.test --funcargs" which shows available funcargs + and their help strings (docstrings on their respective factory function) + for a given test path + +- display a short and concise traceback if a funcarg lookup fails + +- early-load "conftest.py" files in non-dot first-level sub directories. + allows to conveniently keep and access test-related options in a ``test`` + subdir and still add command line options. + +- fix issue67: new super-short traceback-printing option: "--tb=line" will print a single line for each failing (python) test indicating its filename, lineno and the failure value + +- fix issue78: always call python-level teardown functions even if the + according setup failed. This includes refinements for calling setup_module/class functions + which will now only be called once instead of the previous behaviour where they'd be called + multiple times if they raise an exception (including a Skipped exception). Any exception + will be re-corded and associated with all tests in the according module/class scope. + +- fix issue63: assume <40 columns to be a bogus terminal width, default to 80 + +- fix pdb debugging to be in the correct frame on raises-related errors + +- update apipkg.py to fix an issue where recursive imports might + unnecessarily break importing + +- fix plugin links + +Changes between 1.2 and 1.1.1 +===================================== + +- moved dist/looponfailing from py.test core into a new + separately released pytest-xdist plugin. + +- new junitxml plugin: --junitxml=path will generate a junit style xml file + which is processable e.g. by the Hudson CI system. + +- new option: --genscript=path will generate a standalone py.test script + which will not need any libraries installed. thanks to Ralf Schmitt. + +- new option: --ignore will prevent specified path from collection. + Can be specified multiple times. + +- new option: --confcutdir=dir will make py.test only consider conftest + files that are relative to the specified dir. + +- new funcarg: "pytestconfig" is the pytest config object for access + to command line args and can now be easily used in a test. + +- install 'py.test' and `py.which` with a ``-$VERSION`` suffix to + disambiguate between Python3, python2.X, Jython and PyPy installed versions. + +- new "pytestconfig" funcarg allows access to test config object + +- new "pytest_report_header" hook can return additional lines + to be displayed at the header of a test run. + +- (experimental) allow "py.test path::name1::name2::..." for pointing + to a test within a test collection directly. This might eventually + evolve as a full substitute to "-k" specifications. + +- streamlined plugin loading: order is now as documented in + customize.html: setuptools, ENV, commandline, conftest. + also setuptools entry point names are turned to canonical namees ("pytest_*") + +- automatically skip tests that need 'capfd' but have no os.dup + +- allow pytest_generate_tests to be defined in classes as well + +- deprecate usage of 'disabled' attribute in favour of pytestmark +- deprecate definition of Directory, Module, Class and Function nodes + in conftest.py files. Use pytest collect hooks instead. + +- collection/item node specific runtest/collect hooks are only called exactly + on matching conftest.py files, i.e. ones which are exactly below + the filesystem path of an item + +- change: the first pytest_collect_directory hook to return something + will now prevent further hooks to be called. + +- change: figleaf plugin now requires --figleaf to run. Also + change its long command line options to be a bit shorter (see py.test -h). + +- change: pytest doctest plugin is now enabled by default and has a + new option --doctest-glob to set a pattern for file matches. + +- change: remove internal py._* helper vars, only keep py._pydir + +- robustify capturing to survive if custom pytest_runtest_setup + code failed and prevented the capturing setup code from running. + +- make py.test.* helpers provided by default plugins visible early - + works transparently both for pydoc and for interactive sessions + which will regularly see e.g. py.test.mark and py.test.importorskip. + +- simplify internal plugin manager machinery +- simplify internal collection tree by introducing a RootCollector node + +- fix assert reinterpreation that sees a call containing "keyword=..." + +- fix issue66: invoke pytest_sessionstart and pytest_sessionfinish + hooks on slaves during dist-testing, report module/session teardown + hooks correctly. + +- fix issue65: properly handle dist-testing if no + execnet/py lib installed remotely. + +- skip some install-tests if no execnet is available + +- fix docs, fix internal bin/ script generation + + +Changes between 1.1.1 and 1.1.0 +===================================== + +- introduce automatic plugin registration via 'pytest11' + entrypoints via setuptools' pkg_resources.iter_entry_points + +- fix py.test dist-testing to work with execnet >= 1.0.0b4 + +- re-introduce py.test.cmdline.main() for better backward compatibility + +- svn paths: fix a bug with path.check(versioned=True) for svn paths, + allow '%' in svn paths, make svnwc.update() default to interactive mode + like in 1.0.x and add svnwc.update(interactive=False) to inhibit interaction. + +- refine distributed tarball to contain test and no pyc files + +- try harder to have deprecation warnings for py.compat.* accesses + report a correct location + +Changes between 1.1.0 and 1.0.2 +===================================== + +* adjust and improve docs + +* remove py.rest tool and internal namespace - it was + never really advertised and can still be used with + the old release if needed. If there is interest + it could be revived into its own tool i guess. + +* fix issue48 and issue59: raise an Error if the module + from an imported test file does not seem to come from + the filepath - avoids "same-name" confusion that has + been reported repeatedly + +* merged Ronny's nose-compatibility hacks: now + nose-style setup_module() and setup() functions are + supported + +* introduce generalized py.test.mark function marking + +* reshuffle / refine command line grouping + +* deprecate parser.addgroup in favour of getgroup which creates option group + +* add --report command line option that allows to control showing of skipped/xfailed sections + +* generalized skipping: a new way to mark python functions with skipif or xfail + at function, class and modules level based on platform or sys-module attributes. + +* extend py.test.mark decorator to allow for positional args + +* introduce and test "py.cleanup -d" to remove empty directories + +* fix issue #59 - robustify unittest test collection + +* make bpython/help interaction work by adding an __all__ attribute + to ApiModule, cleanup initpkg + +* use MIT license for pylib, add some contributors + +* remove py.execnet code and substitute all usages with 'execnet' proper + +* fix issue50 - cached_setup now caches more to expectations + for test functions with multiple arguments. + +* merge Jarko's fixes, issue #45 and #46 + +* add the ability to specify a path for py.lookup to search in + +* fix a funcarg cached_setup bug probably only occuring + in distributed testing and "module" scope with teardown. + +* many fixes and changes for making the code base python3 compatible, + many thanks to Benjamin Peterson for helping with this. + +* consolidate builtins implementation to be compatible with >=2.3, + add helpers to ease keeping 2 and 3k compatible code + +* deprecate py.compat.doctest|subprocess|textwrap|optparse + +* deprecate py.magic.autopath, remove py/magic directory + +* move pytest assertion handling to py/code and a pytest_assertion + plugin, add "--no-assert" option, deprecate py.magic namespaces + in favour of (less) py.code ones. + +* consolidate and cleanup py/code classes and files + +* cleanup py/misc, move tests to bin-for-dist + +* introduce delattr/delitem/delenv methods to py.test's monkeypatch funcarg + +* consolidate py.log implementation, remove old approach. + +* introduce py.io.TextIO and py.io.BytesIO for distinguishing between + text/unicode and byte-streams (uses underlying standard lib io.* + if available) + +* make py.unittest_convert helper script available which converts "unittest.py" + style files into the simpler assert/direct-test-classes py.test/nosetests + style. The script was written by Laura Creighton. + +* simplified internal localpath implementation + +Changes between 1.0.1 and 1.0.2 +===================================== + +* fixing packaging issues, triggered by fedora redhat packaging, + also added doc, examples and contrib dirs to the tarball. + +* added a documentation link to the new django plugin. + +Changes between 1.0.0 and 1.0.1 +===================================== + +* added a 'pytest_nose' plugin which handles nose.SkipTest, + nose-style function/method/generator setup/teardown and + tries to report functions correctly. + +* capturing of unicode writes or encoded strings to sys.stdout/err + work better, also terminalwriting was adapted and somewhat + unified between windows and linux. + +* improved documentation layout and content a lot + +* added a "--help-config" option to show conftest.py / ENV-var names for + all longopt cmdline options, and some special conftest.py variables. + renamed 'conf_capture' conftest setting to 'option_capture' accordingly. + +* fix issue #27: better reporting on non-collectable items given on commandline + (e.g. pyc files) + +* fix issue #33: added --version flag (thanks Benjamin Peterson) + +* fix issue #32: adding support for "incomplete" paths to wcpath.status() + +* "Test" prefixed classes are *not* collected by default anymore if they + have an __init__ method + +* monkeypatch setenv() now accepts a "prepend" parameter + +* improved reporting of collection error tracebacks + +* simplified multicall mechanism and plugin architecture, + renamed some internal methods and argnames + +Changes between 1.0.0b9 and 1.0.0 +===================================== + +* more terse reporting try to show filesystem path relatively to current dir +* improve xfail output a bit + +Changes between 1.0.0b8 and 1.0.0b9 +===================================== + +* cleanly handle and report final teardown of test setup + +* fix svn-1.6 compat issue with py.path.svnwc().versioned() + (thanks Wouter Vanden Hove) + +* setup/teardown or collection problems now show as ERRORs + or with big "E"'s in the progress lines. they are reported + and counted separately. + +* dist-testing: properly handle test items that get locally + collected but cannot be collected on the remote side - often + due to platform/dependency reasons + +* simplified py.test.mark API - see keyword plugin documentation + +* integrate better with logging: capturing now by default captures + test functions and their immediate setup/teardown in a single stream + +* capsys and capfd funcargs now have a readouterr() and a close() method + (underlyingly py.io.StdCapture/FD objects are used which grew a + readouterr() method as well to return snapshots of captured out/err) + +* make assert-reinterpretation work better with comparisons not + returning bools (reported with numpy from thanks maciej fijalkowski) + +* reworked per-test output capturing into the pytest_iocapture.py plugin + and thus removed capturing code from config object + +* item.repr_failure(excinfo) instead of item.repr_failure(excinfo, outerr) + + +Changes between 1.0.0b7 and 1.0.0b8 +===================================== + +* pytest_unittest-plugin is now enabled by default + +* introduced pytest_keyboardinterrupt hook and + refined pytest_sessionfinish hooked, added tests. + +* workaround a buggy logging module interaction ("closing already closed + files"). Thanks to Sridhar Ratnakumar for triggering. + +* if plugins use "py.test.importorskip" for importing + a dependency only a warning will be issued instead + of exiting the testing process. + +* many improvements to docs: + - refined funcargs doc , use the term "factory" instead of "provider" + - added a new talk/tutorial doc page + - better download page + - better plugin docstrings + - added new plugins page and automatic doc generation script + +* fixed teardown problem related to partially failing funcarg setups + (thanks MrTopf for reporting), "pytest_runtest_teardown" is now + always invoked even if the "pytest_runtest_setup" failed. + +* tweaked doctest output for docstrings in py modules, + thanks Radomir. + +Changes between 1.0.0b3 and 1.0.0b7 +============================================= + +* renamed py.test.xfail back to py.test.mark.xfail to avoid + two ways to decorate for xfail + +* re-added py.test.mark decorator for setting keywords on functions + (it was actually documented so removing it was not nice) + +* remove scope-argument from request.addfinalizer() because + request.cached_setup has the scope arg. TOOWTDI. + +* perform setup finalization before reporting failures + +* apply modified patches from Andreas Kloeckner to allow + test functions to have no func_code (#22) and to make + "-k" and function keywords work (#20) + +* apply patch from Daniel Peolzleithner (issue #23) + +* resolve issue #18, multiprocessing.Manager() and + redirection clash + +* make __name__ == "__channelexec__" for remote_exec code + +Changes between 1.0.0b1 and 1.0.0b3 +============================================= + +* plugin classes are removed: one now defines + hooks directly in conftest.py or global pytest_*.py + files. + +* added new pytest_namespace(config) hook that allows + to inject helpers directly to the py.test.* namespace. + +* documented and refined many hooks + +* added new style of generative tests via + pytest_generate_tests hook that integrates + well with function arguments. + + +Changes between 0.9.2 and 1.0.0b1 +============================================= + +* introduced new "funcarg" setup method, + see doc/test/funcarg.txt + +* introduced plugin architecuture and many + new py.test plugins, see + doc/test/plugins.txt + +* teardown_method is now guaranteed to get + called after a test method has run. + +* new method: py.test.importorskip(mod,minversion) + will either import or call py.test.skip() + +* completely revised internal py.test architecture + +* new py.process.ForkedFunc object allowing to + fork execution of a function to a sub process + and getting a result back. + +XXX lots of things missing here XXX + +Changes between 0.9.1 and 0.9.2 +=============================== + +* refined installation and metadata, created new setup.py, + now based on setuptools/ez_setup (thanks to Ralf Schmitt + for his support). + +* improved the way of making py.* scripts available in + windows environments, they are now added to the + Scripts directory as ".cmd" files. + +* py.path.svnwc.status() now is more complete and + uses xml output from the 'svn' command if available + (Guido Wesdorp) + +* fix for py.path.svn* to work with svn 1.5 + (Chris Lamb) + +* fix path.relto(otherpath) method on windows to + use normcase for checking if a path is relative. + +* py.test's traceback is better parseable from editors + (follows the filenames:LINENO: MSG convention) + (thanks to Osmo Salomaa) + +* fix to javascript-generation, "py.test --runbrowser" + should work more reliably now + +* removed previously accidentally added + py.test.broken and py.test.notimplemented helpers. + +* there now is a py.__version__ attribute + +Changes between 0.9.0 and 0.9.1 +=============================== + +This is a fairly complete list of changes between 0.9 and 0.9.1, which can +serve as a reference for developers. + +* allowing + signs in py.path.svn urls [39106] +* fixed support for Failed exceptions without excinfo in py.test [39340] +* added support for killing processes for Windows (as well as platforms that + support os.kill) in py.misc.killproc [39655] +* added setup/teardown for generative tests to py.test [40702] +* added detection of FAILED TO LOAD MODULE to py.test [40703, 40738, 40739] +* fixed problem with calling .remove() on wcpaths of non-versioned files in + py.path [44248] +* fixed some import and inheritance issues in py.test [41480, 44648, 44655] +* fail to run greenlet tests when pypy is available, but without stackless + [45294] +* small fixes in rsession tests [45295] +* fixed issue with 2.5 type representations in py.test [45483, 45484] +* made that internal reporting issues displaying is done atomically in py.test + [45518] +* made that non-existing files are igored by the py.lookup script [45519] +* improved exception name creation in py.test [45535] +* made that less threads are used in execnet [merge in 45539] +* removed lock required for atomical reporting issue displaying in py.test + [45545] +* removed globals from execnet [45541, 45547] +* refactored cleanup mechanics, made that setDaemon is set to 1 to make atexit + get called in 2.5 (py.execnet) [45548] +* fixed bug in joining threads in py.execnet's servemain [45549] +* refactored py.test.rsession tests to not rely on exact output format anymore + [45646] +* using repr() on test outcome [45647] +* added 'Reason' classes for py.test.skip() [45648, 45649] +* killed some unnecessary sanity check in py.test.collect [45655] +* avoid using os.tmpfile() in py.io.fdcapture because on Windows it's only + usable by Administrators [45901] +* added support for locking and non-recursive commits to py.path.svnwc [45994] +* locking files in py.execnet to prevent CPython from segfaulting [46010] +* added export() method to py.path.svnurl +* fixed -d -x in py.test [47277] +* fixed argument concatenation problem in py.path.svnwc [49423] +* restore py.test behaviour that it exits with code 1 when there are failures + [49974] +* don't fail on html files that don't have an accompanying .txt file [50606] +* fixed 'utestconvert.py < input' [50645] +* small fix for code indentation in py.code.source [50755] +* fix _docgen.py documentation building [51285] +* improved checks for source representation of code blocks in py.test [51292] +* added support for passing authentication to py.path.svn* objects [52000, + 52001] +* removed sorted() call for py.apigen tests in favour of [].sort() to support + Python 2.3 [52481] diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.3.1.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.1.txt new file mode 100644 index 000000000..471de408a --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.1.txt @@ -0,0 +1,104 @@ +py.test/pylib 1.3.1: new py.test.xfail, --maxfail, better reporting +=========================================================================== + +The pylib/py.test 1.3.1 release brings: + +- the new imperative ``py.test.xfail()`` helper in order to have a test or + setup function result in an "expected failure" +- a new option ``--maxfail=NUM`` to stop the test run after some failures +- markers/decorators are now applicable to test classes (>=Python2.6) +- improved reporting, shorter tracebacks in several cases +- some simplified internals, more compatibility with Jython and PyPy +- bug fixes and various refinements + +See the below CHANGELOG entry below for more details and +http://pylib.org/install.html for installation instructions. + +If you used older versions of py.test you should be able to upgrade +to 1.3.1 without changes to your test source code. + +py.test is an automated testing tool working with Python2, +Python3, Jython and PyPy versions on all major operating systems. It +offers a no-boilerplate testing approach and has inspired other testing +tools and enhancements in the standard Python library for more than five +years. It has a simple and extensive plugin architecture, configurable +reporting and provides unique ways to make it fit to your testing +process and needs. + +See http://pytest.org for more info. + +cheers and have fun, + +holger krekel + +Changes between 1.3.0 and 1.3.1 +================================================== + +New features +++++++++++++++++++ + +- issue91: introduce new py.test.xfail(reason) helper + to imperatively mark a test as expected to fail. Can + be used from within setup and test functions. This is + useful especially for parametrized tests when certain + configurations are expected-to-fail. In this case the + declarative approach with the @py.test.mark.xfail cannot + be used as it would mark all configurations as xfail. + +- issue102: introduce new --maxfail=NUM option to stop + test runs after NUM failures. This is a generalization + of the '-x' or '--exitfirst' option which is now equivalent + to '--maxfail=1'. Both '-x' and '--maxfail' will + now also print a line near the end indicating the Interruption. + +- issue89: allow py.test.mark decorators to be used on classes + (class decorators were introduced with python2.6) and + also allow to have multiple markers applied at class/module level + by specifying a list. + +- improve and refine letter reporting in the progress bar: + . pass + f failed test + s skipped tests (reminder: use for dependency/platform mismatch only) + x xfailed test (test that was expected to fail) + X xpassed test (test that was expected to fail but passed) + + You can use any combination of 'fsxX' with the '-r' extended + reporting option. The xfail/xpass results will show up as + skipped tests in the junitxml output - which also fixes + issue99. + +- make py.test.cmdline.main() return the exitstatus instead of raising + SystemExit and also allow it to be called multiple times. This of + course requires that your application and tests are properly teared + down and don't have global state. + +Fixes / Maintenance +++++++++++++++++++++++ + +- improved traceback presentation: + - improved and unified reporting for "--tb=short" option + - Errors during test module imports are much shorter, (using --tb=short style) + - raises shows shorter more relevant tracebacks + - --fulltrace now more systematically makes traces longer / inhibits cutting + +- improve support for raises and other dynamically compiled code by + manipulating python's linecache.cache instead of the previous + rather hacky way of creating custom code objects. This makes + it seemlessly work on Jython and PyPy where it previously didn't. + +- fix issue96: make capturing more resilient against Control-C + interruptions (involved somewhat substantial refactoring + to the underlying capturing functionality to avoid race + conditions). + +- fix chaining of conditional skipif/xfail decorators - so it works now + as expected to use multiple @py.test.mark.skipif(condition) decorators, + including specific reporting which of the conditions lead to skipping. + +- fix issue95: late-import zlib so that it's not required + for general py.test startup. + +- fix issue94: make reporting more robust against bogus source code + (and internally be more careful when presenting unexpected byte sequences) + diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.3.2.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.2.txt new file mode 100644 index 000000000..599dfbed7 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.2.txt @@ -0,0 +1,720 @@ +py.test/pylib 1.3.2: API and reporting refinements, many fixes +=========================================================================== + +The pylib/py.test 1.3.2 release brings many bug fixes and some new +features. It was refined for and tested against the recently released +Python2.7 and remains compatibile to the usual armada of interpreters +(Python2.4 through to Python3.1.2, Jython and PyPy). Note that for using +distributed testing features you'll need to upgrade to the jointly released +pytest-xdist-1.4 because of some internal refactorings. + +See http://pytest.org for general documentation and below for +a detailed CHANGELOG. + +cheers & particular thanks to Benjamin Peterson, Ronny Pfannschmidt +and all issue and patch contributors, + +holger krekel + +Changes between 1.3.1 and 1.3.2 +================================================== + +New features +++++++++++++++++++ + +- fix issue103: introduce py.test.raises as context manager, examples:: + + with py.test.raises(ZeroDivisionError): + x = 0 + 1 / x + + with py.test.raises(RuntimeError) as excinfo: + call_something() + + # you may do extra checks on excinfo.value|type|traceback here + + (thanks Ronny Pfannschmidt) + +- Funcarg factories can now dynamically apply a marker to a + test invocation. This is for example useful if a factory + provides parameters to a test which are expected-to-fail:: + + def pytest_funcarg__arg(request): + request.applymarker(py.test.mark.xfail(reason="flaky config")) + ... + + def test_function(arg): + ... + +- improved error reporting on collection and import errors. This makes + use of a more general mechanism, namely that for custom test item/collect + nodes ``node.repr_failure(excinfo)`` is now uniformly called so that you can + override it to return a string error representation of your choice + which is going to be reported as a (red) string. + +- introduce '--junitprefix=STR' option to prepend a prefix + to all reports in the junitxml file. + +Bug fixes / Maintenance +++++++++++++++++++++++++++ + +- make tests and the ``pytest_recwarn`` plugin in particular fully compatible + to Python2.7 (if you use the ``recwarn`` funcarg warnings will be enabled so that + you can properly check for their existence in a cross-python manner). +- refine --pdb: ignore xfailed tests, unify its TB-reporting and + don't display failures again at the end. +- fix assertion interpretation with the ** operator (thanks Benjamin Peterson) +- fix issue105 assignment on the same line as a failing assertion (thanks Benjamin Peterson) +- fix issue104 proper escaping for test names in junitxml plugin (thanks anonymous) +- fix issue57 -f|--looponfail to work with xpassing tests (thanks Ronny) +- fix issue92 collectonly reporter and --pastebin (thanks Benjamin Peterson) +- fix py.code.compile(source) to generate unique filenames +- fix assertion re-interp problems on PyPy, by defering code + compilation to the (overridable) Frame.eval class. (thanks Amaury Forgeot) +- fix py.path.local.pyimport() to work with directories +- streamline py.path.local.mkdtemp implementation and usage +- don't print empty lines when showing junitxml-filename +- add optional boolean ignore_errors parameter to py.path.local.remove +- fix terminal writing on win32/python2.4 +- py.process.cmdexec() now tries harder to return properly encoded unicode objects + on all python versions +- install plain py.test/py.which scripts also for Jython, this helps to + get canonical script paths in virtualenv situations +- make path.bestrelpath(path) return ".", note that when calling + X.bestrelpath the assumption is that X is a directory. +- make initial conftest discovery ignore "--" prefixed arguments +- fix resultlog plugin when used in an multicpu/multihost xdist situation + (thanks Jakub Gustak) +- perform distributed testing related reporting in the xdist-plugin + rather than having dist-related code in the generic py.test + distribution +- fix homedir detection on Windows +- ship distribute_setup.py version 0.6.13 + +Changes between 1.3.0 and 1.3.1 +================================================== + +New features +++++++++++++++++++ + +- issue91: introduce new py.test.xfail(reason) helper + to imperatively mark a test as expected to fail. Can + be used from within setup and test functions. This is + useful especially for parametrized tests when certain + configurations are expected-to-fail. In this case the + declarative approach with the @py.test.mark.xfail cannot + be used as it would mark all configurations as xfail. + +- issue102: introduce new --maxfail=NUM option to stop + test runs after NUM failures. This is a generalization + of the '-x' or '--exitfirst' option which is now equivalent + to '--maxfail=1'. Both '-x' and '--maxfail' will + now also print a line near the end indicating the Interruption. + +- issue89: allow py.test.mark decorators to be used on classes + (class decorators were introduced with python2.6) and + also allow to have multiple markers applied at class/module level + by specifying a list. + +- improve and refine letter reporting in the progress bar: + . pass + f failed test + s skipped tests (reminder: use for dependency/platform mismatch only) + x xfailed test (test that was expected to fail) + X xpassed test (test that was expected to fail but passed) + + You can use any combination of 'fsxX' with the '-r' extended + reporting option. The xfail/xpass results will show up as + skipped tests in the junitxml output - which also fixes + issue99. + +- make py.test.cmdline.main() return the exitstatus instead of raising + SystemExit and also allow it to be called multiple times. This of + course requires that your application and tests are properly teared + down and don't have global state. + +Fixes / Maintenance +++++++++++++++++++++++ + +- improved traceback presentation: + - improved and unified reporting for "--tb=short" option + - Errors during test module imports are much shorter, (using --tb=short style) + - raises shows shorter more relevant tracebacks + - --fulltrace now more systematically makes traces longer / inhibits cutting + +- improve support for raises and other dynamically compiled code by + manipulating python's linecache.cache instead of the previous + rather hacky way of creating custom code objects. This makes + it seemlessly work on Jython and PyPy where it previously didn't. + +- fix issue96: make capturing more resilient against Control-C + interruptions (involved somewhat substantial refactoring + to the underlying capturing functionality to avoid race + conditions). + +- fix chaining of conditional skipif/xfail decorators - so it works now + as expected to use multiple @py.test.mark.skipif(condition) decorators, + including specific reporting which of the conditions lead to skipping. + +- fix issue95: late-import zlib so that it's not required + for general py.test startup. + +- fix issue94: make reporting more robust against bogus source code + (and internally be more careful when presenting unexpected byte sequences) + + +Changes between 1.2.1 and 1.3.0 +================================================== + +- deprecate --report option in favour of a new shorter and easier to + remember -r option: it takes a string argument consisting of any + combination of 'xfsX' characters. They relate to the single chars + you see during the dotted progress printing and will print an extra line + per test at the end of the test run. This extra line indicates the exact + position or test ID that you directly paste to the py.test cmdline in order + to re-run a particular test. + +- allow external plugins to register new hooks via the new + pytest_addhooks(pluginmanager) hook. The new release of + the pytest-xdist plugin for distributed and looponfailing + testing requires this feature. + +- add a new pytest_ignore_collect(path, config) hook to allow projects and + plugins to define exclusion behaviour for their directory structure - + for example you may define in a conftest.py this method:: + + def pytest_ignore_collect(path): + return path.check(link=1) + + to prevent even a collection try of any tests in symlinked dirs. + +- new pytest_pycollect_makemodule(path, parent) hook for + allowing customization of the Module collection object for a + matching test module. + +- extend and refine xfail mechanism: + ``@py.test.mark.xfail(run=False)`` do not run the decorated test + ``@py.test.mark.xfail(reason="...")`` prints the reason string in xfail summaries + specifiying ``--runxfail`` on command line virtually ignores xfail markers + +- expose (previously internal) commonly useful methods: + py.io.get_terminal_with() -> return terminal width + py.io.ansi_print(...) -> print colored/bold text on linux/win32 + py.io.saferepr(obj) -> return limited representation string + +- expose test outcome related exceptions as py.test.skip.Exception, + py.test.raises.Exception etc., useful mostly for plugins + doing special outcome interpretation/tweaking + +- (issue85) fix junitxml plugin to handle tests with non-ascii output + +- fix/refine python3 compatibility (thanks Benjamin Peterson) + +- fixes for making the jython/win32 combination work, note however: + jython2.5.1/win32 does not provide a command line launcher, see + http://bugs.jython.org/issue1491 . See pylib install documentation + for how to work around. + +- fixes for handling of unicode exception values and unprintable objects + +- (issue87) fix unboundlocal error in assertionold code + +- (issue86) improve documentation for looponfailing + +- refine IO capturing: stdin-redirect pseudo-file now has a NOP close() method + +- ship distribute_setup.py version 0.6.10 + +- added links to the new capturelog and coverage plugins + + +Changes between 1.2.1 and 1.2.0 +===================================== + +- refined usage and options for "py.cleanup":: + + py.cleanup # remove "*.pyc" and "*$py.class" (jython) files + py.cleanup -e .swp -e .cache # also remove files with these extensions + py.cleanup -s # remove "build" and "dist" directory next to setup.py files + py.cleanup -d # also remove empty directories + py.cleanup -a # synonym for "-s -d -e 'pip-log.txt'" + py.cleanup -n # dry run, only show what would be removed + +- add a new option "py.test --funcargs" which shows available funcargs + and their help strings (docstrings on their respective factory function) + for a given test path + +- display a short and concise traceback if a funcarg lookup fails + +- early-load "conftest.py" files in non-dot first-level sub directories. + allows to conveniently keep and access test-related options in a ``test`` + subdir and still add command line options. + +- fix issue67: new super-short traceback-printing option: "--tb=line" will print a single line for each failing (python) test indicating its filename, lineno and the failure value + +- fix issue78: always call python-level teardown functions even if the + according setup failed. This includes refinements for calling setup_module/class functions + which will now only be called once instead of the previous behaviour where they'd be called + multiple times if they raise an exception (including a Skipped exception). Any exception + will be re-corded and associated with all tests in the according module/class scope. + +- fix issue63: assume <40 columns to be a bogus terminal width, default to 80 + +- fix pdb debugging to be in the correct frame on raises-related errors + +- update apipkg.py to fix an issue where recursive imports might + unnecessarily break importing + +- fix plugin links + +Changes between 1.2 and 1.1.1 +===================================== + +- moved dist/looponfailing from py.test core into a new + separately released pytest-xdist plugin. + +- new junitxml plugin: --junitxml=path will generate a junit style xml file + which is processable e.g. by the Hudson CI system. + +- new option: --genscript=path will generate a standalone py.test script + which will not need any libraries installed. thanks to Ralf Schmitt. + +- new option: --ignore will prevent specified path from collection. + Can be specified multiple times. + +- new option: --confcutdir=dir will make py.test only consider conftest + files that are relative to the specified dir. + +- new funcarg: "pytestconfig" is the pytest config object for access + to command line args and can now be easily used in a test. + +- install 'py.test' and `py.which` with a ``-$VERSION`` suffix to + disambiguate between Python3, python2.X, Jython and PyPy installed versions. + +- new "pytestconfig" funcarg allows access to test config object + +- new "pytest_report_header" hook can return additional lines + to be displayed at the header of a test run. + +- (experimental) allow "py.test path::name1::name2::..." for pointing + to a test within a test collection directly. This might eventually + evolve as a full substitute to "-k" specifications. + +- streamlined plugin loading: order is now as documented in + customize.html: setuptools, ENV, commandline, conftest. + also setuptools entry point names are turned to canonical namees ("pytest_*") + +- automatically skip tests that need 'capfd' but have no os.dup + +- allow pytest_generate_tests to be defined in classes as well + +- deprecate usage of 'disabled' attribute in favour of pytestmark +- deprecate definition of Directory, Module, Class and Function nodes + in conftest.py files. Use pytest collect hooks instead. + +- collection/item node specific runtest/collect hooks are only called exactly + on matching conftest.py files, i.e. ones which are exactly below + the filesystem path of an item + +- change: the first pytest_collect_directory hook to return something + will now prevent further hooks to be called. + +- change: figleaf plugin now requires --figleaf to run. Also + change its long command line options to be a bit shorter (see py.test -h). + +- change: pytest doctest plugin is now enabled by default and has a + new option --doctest-glob to set a pattern for file matches. + +- change: remove internal py._* helper vars, only keep py._pydir + +- robustify capturing to survive if custom pytest_runtest_setup + code failed and prevented the capturing setup code from running. + +- make py.test.* helpers provided by default plugins visible early - + works transparently both for pydoc and for interactive sessions + which will regularly see e.g. py.test.mark and py.test.importorskip. + +- simplify internal plugin manager machinery +- simplify internal collection tree by introducing a RootCollector node + +- fix assert reinterpreation that sees a call containing "keyword=..." + +- fix issue66: invoke pytest_sessionstart and pytest_sessionfinish + hooks on slaves during dist-testing, report module/session teardown + hooks correctly. + +- fix issue65: properly handle dist-testing if no + execnet/py lib installed remotely. + +- skip some install-tests if no execnet is available + +- fix docs, fix internal bin/ script generation + + +Changes between 1.1.1 and 1.1.0 +===================================== + +- introduce automatic plugin registration via 'pytest11' + entrypoints via setuptools' pkg_resources.iter_entry_points + +- fix py.test dist-testing to work with execnet >= 1.0.0b4 + +- re-introduce py.test.cmdline.main() for better backward compatibility + +- svn paths: fix a bug with path.check(versioned=True) for svn paths, + allow '%' in svn paths, make svnwc.update() default to interactive mode + like in 1.0.x and add svnwc.update(interactive=False) to inhibit interaction. + +- refine distributed tarball to contain test and no pyc files + +- try harder to have deprecation warnings for py.compat.* accesses + report a correct location + +Changes between 1.1.0 and 1.0.2 +===================================== + +* adjust and improve docs + +* remove py.rest tool and internal namespace - it was + never really advertised and can still be used with + the old release if needed. If there is interest + it could be revived into its own tool i guess. + +* fix issue48 and issue59: raise an Error if the module + from an imported test file does not seem to come from + the filepath - avoids "same-name" confusion that has + been reported repeatedly + +* merged Ronny's nose-compatibility hacks: now + nose-style setup_module() and setup() functions are + supported + +* introduce generalized py.test.mark function marking + +* reshuffle / refine command line grouping + +* deprecate parser.addgroup in favour of getgroup which creates option group + +* add --report command line option that allows to control showing of skipped/xfailed sections + +* generalized skipping: a new way to mark python functions with skipif or xfail + at function, class and modules level based on platform or sys-module attributes. + +* extend py.test.mark decorator to allow for positional args + +* introduce and test "py.cleanup -d" to remove empty directories + +* fix issue #59 - robustify unittest test collection + +* make bpython/help interaction work by adding an __all__ attribute + to ApiModule, cleanup initpkg + +* use MIT license for pylib, add some contributors + +* remove py.execnet code and substitute all usages with 'execnet' proper + +* fix issue50 - cached_setup now caches more to expectations + for test functions with multiple arguments. + +* merge Jarko's fixes, issue #45 and #46 + +* add the ability to specify a path for py.lookup to search in + +* fix a funcarg cached_setup bug probably only occuring + in distributed testing and "module" scope with teardown. + +* many fixes and changes for making the code base python3 compatible, + many thanks to Benjamin Peterson for helping with this. + +* consolidate builtins implementation to be compatible with >=2.3, + add helpers to ease keeping 2 and 3k compatible code + +* deprecate py.compat.doctest|subprocess|textwrap|optparse + +* deprecate py.magic.autopath, remove py/magic directory + +* move pytest assertion handling to py/code and a pytest_assertion + plugin, add "--no-assert" option, deprecate py.magic namespaces + in favour of (less) py.code ones. + +* consolidate and cleanup py/code classes and files + +* cleanup py/misc, move tests to bin-for-dist + +* introduce delattr/delitem/delenv methods to py.test's monkeypatch funcarg + +* consolidate py.log implementation, remove old approach. + +* introduce py.io.TextIO and py.io.BytesIO for distinguishing between + text/unicode and byte-streams (uses underlying standard lib io.* + if available) + +* make py.unittest_convert helper script available which converts "unittest.py" + style files into the simpler assert/direct-test-classes py.test/nosetests + style. The script was written by Laura Creighton. + +* simplified internal localpath implementation + +Changes between 1.0.1 and 1.0.2 +===================================== + +* fixing packaging issues, triggered by fedora redhat packaging, + also added doc, examples and contrib dirs to the tarball. + +* added a documentation link to the new django plugin. + +Changes between 1.0.0 and 1.0.1 +===================================== + +* added a 'pytest_nose' plugin which handles nose.SkipTest, + nose-style function/method/generator setup/teardown and + tries to report functions correctly. + +* capturing of unicode writes or encoded strings to sys.stdout/err + work better, also terminalwriting was adapted and somewhat + unified between windows and linux. + +* improved documentation layout and content a lot + +* added a "--help-config" option to show conftest.py / ENV-var names for + all longopt cmdline options, and some special conftest.py variables. + renamed 'conf_capture' conftest setting to 'option_capture' accordingly. + +* fix issue #27: better reporting on non-collectable items given on commandline + (e.g. pyc files) + +* fix issue #33: added --version flag (thanks Benjamin Peterson) + +* fix issue #32: adding support for "incomplete" paths to wcpath.status() + +* "Test" prefixed classes are *not* collected by default anymore if they + have an __init__ method + +* monkeypatch setenv() now accepts a "prepend" parameter + +* improved reporting of collection error tracebacks + +* simplified multicall mechanism and plugin architecture, + renamed some internal methods and argnames + +Changes between 1.0.0b9 and 1.0.0 +===================================== + +* more terse reporting try to show filesystem path relatively to current dir +* improve xfail output a bit + +Changes between 1.0.0b8 and 1.0.0b9 +===================================== + +* cleanly handle and report final teardown of test setup + +* fix svn-1.6 compat issue with py.path.svnwc().versioned() + (thanks Wouter Vanden Hove) + +* setup/teardown or collection problems now show as ERRORs + or with big "E"'s in the progress lines. they are reported + and counted separately. + +* dist-testing: properly handle test items that get locally + collected but cannot be collected on the remote side - often + due to platform/dependency reasons + +* simplified py.test.mark API - see keyword plugin documentation + +* integrate better with logging: capturing now by default captures + test functions and their immediate setup/teardown in a single stream + +* capsys and capfd funcargs now have a readouterr() and a close() method + (underlyingly py.io.StdCapture/FD objects are used which grew a + readouterr() method as well to return snapshots of captured out/err) + +* make assert-reinterpretation work better with comparisons not + returning bools (reported with numpy from thanks maciej fijalkowski) + +* reworked per-test output capturing into the pytest_iocapture.py plugin + and thus removed capturing code from config object + +* item.repr_failure(excinfo) instead of item.repr_failure(excinfo, outerr) + + +Changes between 1.0.0b7 and 1.0.0b8 +===================================== + +* pytest_unittest-plugin is now enabled by default + +* introduced pytest_keyboardinterrupt hook and + refined pytest_sessionfinish hooked, added tests. + +* workaround a buggy logging module interaction ("closing already closed + files"). Thanks to Sridhar Ratnakumar for triggering. + +* if plugins use "py.test.importorskip" for importing + a dependency only a warning will be issued instead + of exiting the testing process. + +* many improvements to docs: + - refined funcargs doc , use the term "factory" instead of "provider" + - added a new talk/tutorial doc page + - better download page + - better plugin docstrings + - added new plugins page and automatic doc generation script + +* fixed teardown problem related to partially failing funcarg setups + (thanks MrTopf for reporting), "pytest_runtest_teardown" is now + always invoked even if the "pytest_runtest_setup" failed. + +* tweaked doctest output for docstrings in py modules, + thanks Radomir. + +Changes between 1.0.0b3 and 1.0.0b7 +============================================= + +* renamed py.test.xfail back to py.test.mark.xfail to avoid + two ways to decorate for xfail + +* re-added py.test.mark decorator for setting keywords on functions + (it was actually documented so removing it was not nice) + +* remove scope-argument from request.addfinalizer() because + request.cached_setup has the scope arg. TOOWTDI. + +* perform setup finalization before reporting failures + +* apply modified patches from Andreas Kloeckner to allow + test functions to have no func_code (#22) and to make + "-k" and function keywords work (#20) + +* apply patch from Daniel Peolzleithner (issue #23) + +* resolve issue #18, multiprocessing.Manager() and + redirection clash + +* make __name__ == "__channelexec__" for remote_exec code + +Changes between 1.0.0b1 and 1.0.0b3 +============================================= + +* plugin classes are removed: one now defines + hooks directly in conftest.py or global pytest_*.py + files. + +* added new pytest_namespace(config) hook that allows + to inject helpers directly to the py.test.* namespace. + +* documented and refined many hooks + +* added new style of generative tests via + pytest_generate_tests hook that integrates + well with function arguments. + + +Changes between 0.9.2 and 1.0.0b1 +============================================= + +* introduced new "funcarg" setup method, + see doc/test/funcarg.txt + +* introduced plugin architecuture and many + new py.test plugins, see + doc/test/plugins.txt + +* teardown_method is now guaranteed to get + called after a test method has run. + +* new method: py.test.importorskip(mod,minversion) + will either import or call py.test.skip() + +* completely revised internal py.test architecture + +* new py.process.ForkedFunc object allowing to + fork execution of a function to a sub process + and getting a result back. + +XXX lots of things missing here XXX + +Changes between 0.9.1 and 0.9.2 +=============================== + +* refined installation and metadata, created new setup.py, + now based on setuptools/ez_setup (thanks to Ralf Schmitt + for his support). + +* improved the way of making py.* scripts available in + windows environments, they are now added to the + Scripts directory as ".cmd" files. + +* py.path.svnwc.status() now is more complete and + uses xml output from the 'svn' command if available + (Guido Wesdorp) + +* fix for py.path.svn* to work with svn 1.5 + (Chris Lamb) + +* fix path.relto(otherpath) method on windows to + use normcase for checking if a path is relative. + +* py.test's traceback is better parseable from editors + (follows the filenames:LINENO: MSG convention) + (thanks to Osmo Salomaa) + +* fix to javascript-generation, "py.test --runbrowser" + should work more reliably now + +* removed previously accidentally added + py.test.broken and py.test.notimplemented helpers. + +* there now is a py.__version__ attribute + +Changes between 0.9.0 and 0.9.1 +=============================== + +This is a fairly complete list of changes between 0.9 and 0.9.1, which can +serve as a reference for developers. + +* allowing + signs in py.path.svn urls [39106] +* fixed support for Failed exceptions without excinfo in py.test [39340] +* added support for killing processes for Windows (as well as platforms that + support os.kill) in py.misc.killproc [39655] +* added setup/teardown for generative tests to py.test [40702] +* added detection of FAILED TO LOAD MODULE to py.test [40703, 40738, 40739] +* fixed problem with calling .remove() on wcpaths of non-versioned files in + py.path [44248] +* fixed some import and inheritance issues in py.test [41480, 44648, 44655] +* fail to run greenlet tests when pypy is available, but without stackless + [45294] +* small fixes in rsession tests [45295] +* fixed issue with 2.5 type representations in py.test [45483, 45484] +* made that internal reporting issues displaying is done atomically in py.test + [45518] +* made that non-existing files are igored by the py.lookup script [45519] +* improved exception name creation in py.test [45535] +* made that less threads are used in execnet [merge in 45539] +* removed lock required for atomical reporting issue displaying in py.test + [45545] +* removed globals from execnet [45541, 45547] +* refactored cleanup mechanics, made that setDaemon is set to 1 to make atexit + get called in 2.5 (py.execnet) [45548] +* fixed bug in joining threads in py.execnet's servemain [45549] +* refactored py.test.rsession tests to not rely on exact output format anymore + [45646] +* using repr() on test outcome [45647] +* added 'Reason' classes for py.test.skip() [45648, 45649] +* killed some unnecessary sanity check in py.test.collect [45655] +* avoid using os.tmpfile() in py.io.fdcapture because on Windows it's only + usable by Administrators [45901] +* added support for locking and non-recursive commits to py.path.svnwc [45994] +* locking files in py.execnet to prevent CPython from segfaulting [46010] +* added export() method to py.path.svnurl +* fixed -d -x in py.test [47277] +* fixed argument concatenation problem in py.path.svnwc [49423] +* restore py.test behaviour that it exits with code 1 when there are failures + [49974] +* don't fail on html files that don't have an accompanying .txt file [50606] +* fixed 'utestconvert.py < input' [50645] +* small fix for code indentation in py.code.source [50755] +* fix _docgen.py documentation building [51285] +* improved checks for source representation of code blocks in py.test [51292] +* added support for passing authentication to py.path.svn* objects [52000, + 52001] +* removed sorted() call for py.apigen tests in favour of [].sort() to support + Python 2.3 [52481] diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.3.3.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.3.txt new file mode 100644 index 000000000..c62cb8590 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.3.txt @@ -0,0 +1,26 @@ +py.test/pylib 1.3.3: windows and other fixes +=========================================================================== + +pylib/py.test 1.3.3 is a minor bugfix release featuring some improvements +and fixes. See changelog_ for full history. + +have fun, +holger krekel + +.. _changelog: ../changelog.html + +Changes between 1.3.2 and 1.3.3 +================================================== + +- fix issue113: assertion representation problem with triple-quoted strings + (and possibly other cases) +- make conftest loading detect that a conftest file with the same + content was already loaded, avoids surprises in nested directory structures + which can be produced e.g. by Hudson. It probably removes the need to use + --confcutdir in most cases. +- fix terminal coloring for win32 + (thanks Michael Foord for reporting) +- fix weirdness: make terminal width detection work on stdout instead of stdin + (thanks Armin Ronacher for reporting) +- remove trailing whitespace in all py/text distribution files + diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.3.4.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.4.txt new file mode 100644 index 000000000..c156c8bdb --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.3.4.txt @@ -0,0 +1,22 @@ +py.test/pylib 1.3.4: fixes and new native traceback option +=========================================================================== + +pylib/py.test 1.3.4 is a minor maintenance release mostly containing bug fixes +and a new "--tb=native" traceback option to show "normal" Python standard +tracebacks instead of the py.test enhanced tracebacks. See below for more +change info and http://pytest.org for more general information on features +and configuration of the testing tool. + +Thanks to the issue reporters and generally to Ronny Pfannschmidt for help. + +cheers, +holger krekel + +Changes between 1.3.3 and 1.3.4 +================================================== + +- fix issue111: improve install documentation for windows +- fix issue119: fix custom collectability of __init__.py as a module +- fix issue116: --doctestmodules work with __init__.py files as well +- fix issue115: unify internal exception passthrough/catching/GeneratorExit +- fix issue118: new --tb=native for presenting cpython-standard exceptions diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.4.0.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.4.0.txt new file mode 100644 index 000000000..6f9a7714d --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.4.0.txt @@ -0,0 +1,47 @@ + +.. _`release-1.4.0`: + +py-1.4.0: cross-python lib for path, code, io, ... manipulations +=========================================================================== + +"py" is a small library comprising APIs for filesystem and svn path +manipulations, dynamic code construction and introspection, a Py2/Py3 +compatibility namespace ("py.builtin"), IO capturing, terminal colored printing +(on windows and linux), ini-file parsing and a lazy import mechanism. +It runs unmodified on all Python interpreters compatible to Python2.4 up +until Python 3.2. The general goal with "py" is to provide stable APIs +for some common tasks that are continously tested against many Python +interpreters and thus also to help transition. Here are some docs: + + http://pylib.org + +NOTE: The prior py-1.3.X versions contained "py.test" which now comes +as its own separate "pytest" distribution and was just released +as "pytest-2.0.0", see here for the revamped docs: + + http://pytest.org + +And "py.cleanup|py.lookup|py.countloc" etc. helpers are now part of +the pycmd distribution, see http://pypi.python.org/pypi/pycmd + +This makes "py-1.4.0" a simple library which does not install +any command line utilities anymore. + +cheers, +holger + +Changes between 1.3.4 and 1.4.0 +------------------------------------- + +- 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 "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() +- path objects have a .dirname attribute now (equivalent to + os.path.dirname(path)) +- path.visit() accepts breadthfirst (bf) and sort options +- remove deprecated py.compat namespace diff --git a/testing/web-platform/tests/tools/py/doc/announce/release-1.4.1.txt b/testing/web-platform/tests/tools/py/doc/announce/release-1.4.1.txt new file mode 100644 index 000000000..a5aa76b14 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/release-1.4.1.txt @@ -0,0 +1,47 @@ + +.. _`release-1.4.1`: + +py-1.4.1: cross-python lib for fs path, code, io, ... manipulations +=========================================================================== + +This is a bug fix release of the "py" lib, see below for detailed changes. +The py lib is a small library comprising APIs for filesystem and svn path +manipulations, dynamic code construction and introspection, a Py2/Py3 +compatibility namespace ("py.builtin"), IO capturing, terminal colored printing +(on windows and linux), ini-file parsing and a lazy import mechanism. +It runs unmodified on all Python interpreters compatible to Python2.4 up +until Python 3.2, PyPy and Jython. The general goal with "py" is to +provide stable APIs for some common tasks that are continously tested +against many Python interpreters and thus also to help transition. Here +are some docs: + + http://pylib.org + +NOTE: The prior py-1.3.X versions contained "py.test" which since py-1.4.0 +comes as its own separate "pytest" distribution, see: + + http://pytest.org + +Also, the "py.cleanup|py.lookup|py.countloc" helpers are now part of +the pycmd distribution, see http://pypi.python.org/pypi/pycmd + + +Changes between 1.4.0 and 1.4.1 +================================================== + +- fix issue1 - py.error.* classes to be pickleable + +- fix issue2 - on windows32 use PATHEXT as the list of potential + extensions to find find binaries with py.path.local.sysfind(commandname) + +- fix (pytest-) issue10 and refine assertion reinterpretation + to avoid breaking if the __nonzero__ of an object fails + +- fix (pytest-) issue17 where python3 does not like star-imports, + leading to misrepresentation of import-errors in test modules + +- fix ``py.error.*`` attribute pypy access + +- allow path.samefile(arg) to succeed when arg is a relative filename + +- fix (pytest-) issue20 path.samefile(relpath) works as expected now diff --git a/testing/web-platform/tests/tools/py/doc/announce/releases.txt b/testing/web-platform/tests/tools/py/doc/announce/releases.txt new file mode 100644 index 000000000..309c29bac --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/announce/releases.txt @@ -0,0 +1,16 @@ +============= +Release notes +============= + +Contents: + +.. toctree:: + :maxdepth: 2 + +.. include: release-1.1.0 +.. include: release-1.0.2 + + release-1.0.1 + release-1.0.0 + release-0.9.2 + release-0.9.0 diff --git a/testing/web-platform/tests/tools/py/doc/changelog.txt b/testing/web-platform/tests/tools/py/doc/changelog.txt new file mode 100644 index 000000000..237daca35 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/changelog.txt @@ -0,0 +1,3 @@ +.. _`changelog`: + +.. include:: ../CHANGELOG diff --git a/testing/web-platform/tests/tools/py/doc/code.txt b/testing/web-platform/tests/tools/py/doc/code.txt new file mode 100644 index 000000000..bdd8691da --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/code.txt @@ -0,0 +1,150 @@ +================================================================================ +py.code: higher level python code and introspection objects +================================================================================ + +``py.code`` provides higher level APIs and objects for Code, Frame, Traceback, +ExceptionInfo and source code construction. The ``py.code`` library +tries to simplify accessing the code objects as well as creating them. +There is a small set of interfaces a user needs to deal with, all nicely +bundled together, and with a rich set of 'Pythonic' functionality. + +Contents of the library +======================= + +Every object in the ``py.code`` library wraps a code Python object related +to code objects, source code, frames and tracebacks: the ``py.code.Code`` +class wraps code objects, ``py.code.Source`` source snippets, +``py.code.Traceback` exception tracebacks, ``py.code.Frame`` frame +objects (as found in e.g. tracebacks) and ``py.code.ExceptionInfo`` the +tuple provided by sys.exc_info() (containing exception and traceback +information when an exception occurs). Also in the library is a helper function +``py.code.compile()`` that provides the same functionality as Python's +built-in 'compile()' function, but returns a wrapped code object. + +The wrappers +============ + +``py.code.Code`` +------------------- + +Code objects are instantiated with a code object or a callable as argument, +and provide functionality to compare themselves with other Code objects, get to +the source file or its contents, create new Code objects from scratch, etc. + +A quick example:: + + >>> import py + >>> c = py.code.Code(py.path.local.read) + >>> c.path.basename + 'common.py' + >>> isinstance(c.source(), py.code.Source) + True + >>> str(c.source()).split('\n')[0] + "def read(self, mode='r'):" + +.. autoclass:: py.code.Code + :members: + :inherited-members: + + +``py.code.Source`` +--------------------- + +Source objects wrap snippets of Python source code, providing a simple yet +powerful interface to read, deindent, slice, compare, compile and manipulate +them, things that are not so easy in core Python. + +Example:: + + >>> s = py.code.Source("""\ + ... def foo(): + ... print "foo" + ... """) + >>> str(s).startswith('def') # automatic de-indentation! + True + >>> s.isparseable() + True + >>> sub = s.getstatement(1) # get the statement starting at line 1 + >>> str(sub).strip() # XXX why is the strip() required?!? + 'print "foo"' + +.. autoclass:: py.code.Source + :members: + + +``py.code.Traceback`` +------------------------ + +Tracebacks are usually not very easy to examine, you need to access certain +somewhat hidden attributes of the traceback's items (resulting in expressions +such as 'fname = tb.tb_next.tb_frame.f_code.co_filename'). The Traceback +interface (and its TracebackItem children) tries to improve this. + +Example:: + + >>> import sys + >>> try: + ... py.path.local(100) # illegal argument + ... except: + ... exc, e, tb = sys.exc_info() + >>> t = py.code.Traceback(tb) + >>> first = t[1] # get the second entry (first is in this doc) + >>> first.path.basename # second is in py/path/local.py + 'local.py' + >>> isinstance(first.statement, py.code.Source) + True + >>> str(first.statement).strip().startswith('raise ValueError') + True + +.. autoclass:: py.code.Traceback + :members: + +``py.code.Frame`` +-------------------- + +Frame wrappers are used in ``py.code.Traceback`` items, and will usually not +directly be instantiated. They provide some nice methods to evaluate code +'inside' the frame (using the frame's local variables), get to the underlying +code (frames have a code attribute that points to a ``py.code.Code`` object) +and examine the arguments. + +Example (using the 'first' TracebackItem instance created above):: + + >>> frame = first.frame + >>> isinstance(frame.code, py.code.Code) + True + >>> isinstance(frame.eval('self'), py.path.local) + True + >>> [namevalue[0] for namevalue in frame.getargs()] + ['cls', 'path'] + +.. autoclass:: py.code.Frame + :members: + +``py.code.ExceptionInfo`` +---------------------------- + +A wrapper around the tuple returned by sys.exc_info() (will call sys.exc_info() +itself if the tuple is not provided as an argument), provides some handy +attributes to easily access the traceback and exception string. + +Example:: + + >>> import sys + >>> try: + ... foobar() + ... except: + ... excinfo = py.code.ExceptionInfo() + >>> excinfo.typename + 'NameError' + >>> isinstance(excinfo.traceback, py.code.Traceback) + True + >>> excinfo.exconly() + "NameError: name 'foobar' is not defined" + +.. autoclass:: py.code.ExceptionInfo + :members: + +.. autoclass:: py.code.Traceback + :members: + diff --git a/testing/web-platform/tests/tools/py/doc/conf.py b/testing/web-platform/tests/tools/py/doc/conf.py new file mode 100644 index 000000000..de4cbf8a4 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/conf.py @@ -0,0 +1,263 @@ +# -*- coding: utf-8 -*- +# +# py 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'py' +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. +# The full version, including alpha/beta/rc tags. +import py +release = py.__version__ +version = ".".join(release.split(".")[:2]) + +# 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 = 'py' + + +# -- 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', 'py.tex', u'py 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', 'py', u'py 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'py' +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} diff --git a/testing/web-platform/tests/tools/py/doc/download.html b/testing/web-platform/tests/tools/py/doc/download.html new file mode 100644 index 000000000..5f4c46640 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/download.html @@ -0,0 +1,18 @@ +<html> + <head> + <meta http-equiv="refresh" content=" 1 ; URL=install.html" /> + </head> + + <body> +<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> +</body> +</html> + diff --git a/testing/web-platform/tests/tools/py/doc/example/genhtml.py b/testing/web-platform/tests/tools/py/doc/example/genhtml.py new file mode 100644 index 000000000..b5c8f525b --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/example/genhtml.py @@ -0,0 +1,13 @@ +from py.xml import html + +paras = "First Para", "Second para" + +doc = html.html( + html.head( + html.meta(name="Content-Type", value="text/html; charset=latin1")), + html.body( + [html.p(p) for p in paras])) + +print unicode(doc).encode('latin1') + + diff --git a/testing/web-platform/tests/tools/py/doc/example/genhtmlcss.py b/testing/web-platform/tests/tools/py/doc/example/genhtmlcss.py new file mode 100644 index 000000000..3e6d0af54 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/example/genhtmlcss.py @@ -0,0 +1,23 @@ +import py +html = py.xml.html + +class my(html): + "a custom style" + class body(html.body): + style = html.Style(font_size = "120%") + + class h2(html.h2): + style = html.Style(background = "grey") + + class p(html.p): + style = html.Style(font_weight="bold") + +doc = my.html( + my.head(), + my.body( + my.h2("hello world"), + my.p("bold as bold can") + ) +) + +print doc.unicode(indent=2) diff --git a/testing/web-platform/tests/tools/py/doc/example/genxml.py b/testing/web-platform/tests/tools/py/doc/example/genxml.py new file mode 100644 index 000000000..5f754e889 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/example/genxml.py @@ -0,0 +1,17 @@ + +import py +class ns(py.xml.Namespace): + pass + +doc = ns.books( + ns.book( + ns.author("May Day"), + ns.title("python for java programmers"),), + ns.book( + ns.author("why", class_="somecssclass"), + ns.title("Java for Python programmers"),), + publisher="N.N", + ) +print doc.unicode(indent=2).encode('utf8') + + diff --git a/testing/web-platform/tests/tools/py/doc/faq.txt b/testing/web-platform/tests/tools/py/doc/faq.txt new file mode 100644 index 000000000..52cb4b3fb --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/faq.txt @@ -0,0 +1,172 @@ +================================== +Frequently Asked Questions +================================== + +.. contents:: + :local: + :depth: 2 + + +On naming, nosetests, licensing and magic +=========================================== + +Why the ``py`` naming? Why not ``pytest``? +---------------------------------------------------- + +This mostly has historic reasons - the aim is +to get away from the somewhat questionable 'py' name +at some point. These days (2010) the 'py' library +almost completely comprises APIs that are used +by the ``py.test`` tool. There also are some +other uses, e.g. of the ``py.path.local()`` and +other path implementations. So it requires some +work to factor them out and do the shift. + +Why the ``py.test`` naming? +------------------------------------ + +because of TAB-completion under Bash/Shells. If you hit +``py.<TAB>`` you'll get a list of available development +tools that all share the ``py.`` prefix. Another motivation +was to unify the package ("py.test") and tool filename. + +What's py.test's relation to ``nosetests``? +--------------------------------------------- + +py.test and nose_ share basic philosophy when it comes +to running Python tests. In fact, +with py.test-1.1.0 it is ever easier to run many test suites +that currently work with ``nosetests``. nose_ was created +as a clone of ``py.test`` when py.test was in the ``0.8`` release +cycle so some of the newer features_ introduced with py.test-1.0 +and py.test-1.1 have no counterpart in nose_. + +.. _nose: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/ +.. _features: test/features.html +.. _apipkg: http://pypi.python.org/pypi/apipkg + + +What's this "magic" with py.test? +---------------------------------------- + +issues where people have used the term "magic" in the past: + +* `py/__init__.py`_ uses the apipkg_ mechanism for lazy-importing + and full control on what API you get when importing "import py". + +* when an ``assert`` statement fails, py.test re-interprets the expression + to show intermediate values if a test fails. If your expression + has side effects the intermediate values may not be the same, obfuscating + the initial error (this is also explained at the command line if it happens). + ``py.test --no-assert`` turns off assert re-intepretation. + Sidenote: it is good practise to avoid asserts with side effects. + + +.. _`py namespaces`: index.html +.. _`py/__init__.py`: http://bitbucket.org/hpk42/py-trunk/src/trunk/py/__init__.py + +Where does my ``py.test`` come/import from? +---------------------------------------------- + +You can issue:: + + py.test --version + +which tells you both version and import location of the tool. + + +function arguments, parametrized tests and setup +==================================================== + +.. _funcargs: test/funcargs.html + +Is using funcarg- versus xUnit-based setup a style question? +--------------------------------------------------------------- + +It depends. For simple applications or for people experienced +with nose_ or unittest-style test setup using `xUnit style setup`_ +make some sense. For larger test suites, parametrized testing +or setup of complex test resources using funcargs_ is recommended. +Moreover, funcargs are ideal for writing advanced test support +code (like e.g. the monkeypatch_, the tmpdir_ or capture_ funcargs) +because the support code can register setup/teardown functions +in a managed class/module/function scope. + +.. _monkeypatch: test/plugin/monkeypatch.html +.. _tmpdir: test/plugin/tmpdir.html +.. _capture: test/plugin/capture.html +.. _`xUnit style setup`: test/xunit_setup.html +.. _`pytest_nose`: test/plugin/nose.html + +.. _`why pytest_pyfuncarg__ methods?`: + +Why the ``pytest_funcarg__*`` name for funcarg factories? +--------------------------------------------------------------- + +When experimenting with funcargs an explicit registration mechanism +was considered. But lacking a good use case for this indirection and +flexibility we decided to go for `Convention over Configuration`_ and +allow to directly specify the factory. Besides removing the need +for an indirection it allows to "grep" for ``pytest_funcarg__MYARG`` +and will safely find all factory functions for the ``MYARG`` function +argument. It helps to alleviate the de-coupling of function +argument usage and creation. + +.. _`Convention over Configuration`: http://en.wikipedia.org/wiki/Convention_over_Configuration + +Can I yield multiple values from a factory function? +----------------------------------------------------- + +There are two conceptual reasons why yielding from a factory function +is not possible: + +* Calling factories for obtaining test function arguments + is part of setting up and running a test. At that + point it is not possible to add new test calls to + the test collection anymore. + +* If multiple factories yielded values there would + be no natural place to determine the combination + policy - in real-world examples some combinations + often should not run. + +Use the `pytest_generate_tests`_ hook to solve both issues +and implement the `parametrization scheme of your choice`_. + +.. _`pytest_generate_tests`: test/funcargs.html#parametrizing-tests +.. _`parametrization scheme of your choice`: http://tetamap.wordpress.com/2009/05/13/parametrizing-python-tests-generalized/ + + +py.test interaction with other packages +=============================================== + +Issues with py.test, multiprocess and setuptools? +------------------------------------------------------------ + +On windows the multiprocess package will instantiate sub processes +by pickling and thus implicitely re-import a lot of local modules. +Unfortuantely, setuptools-0.6.11 does not ``if __name__=='__main__'`` +protect its generated command line script. This leads to infinite +recursion when running a test that instantiates Processes. +There are these workarounds: + +* `install Distribute`_ as a drop-in replacement for setuptools + and install py.test + +* `directly use a checkout`_ which avoids all setuptools/Distribute + installation + +If those options are not available to you, you may also manually +fix the script that is created by setuptools by inserting an +``if __name__ == '__main__'``. Or you can create a "pytest.py" +script with this content and invoke that with the python version:: + + import py + if __name__ == '__main__': + py.cmdline.pytest() + +.. _`directly use a checkout`: install.html#directly-use-a-checkout + +.. _`install distribute`: http://pypi.python.org/pypi/distribute#installation-instructions + + diff --git a/testing/web-platform/tests/tools/py/doc/img/pylib.png b/testing/web-platform/tests/tools/py/doc/img/pylib.png Binary files differnew file mode 100644 index 000000000..2e10d4388 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/img/pylib.png diff --git a/testing/web-platform/tests/tools/py/doc/index.txt b/testing/web-platform/tests/tools/py/doc/index.txt new file mode 100644 index 000000000..7eb5c6390 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/index.txt @@ -0,0 +1,43 @@ +.. py 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. + +Welcome to py's documentation! +================================= + +see :ref:`CHANGELOG <changelog>` for latest changes. + +.. note:: + + Since version 1.4, the testing tool "py.test" is part of its own `pytest distribution`_. + +.. _`pytest distribution`: http://pytest.org + +Contents: + +.. toctree:: + + install + path + code + io + log + xml + misc + + :maxdepth: 2 + +.. toctree:: + :hidden: + + announce/release-2.0.0 + changelog + announce/* + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`search` + diff --git a/testing/web-platform/tests/tools/py/doc/install.txt b/testing/web-platform/tests/tools/py/doc/install.txt new file mode 100644 index 000000000..d0e981def --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/install.txt @@ -0,0 +1,88 @@ + +.. _`py`: +.. _`index page`: http://pypi.python.org/pypi/py/ + +installation info in a nutshell +=================================================== + +**PyPI name**: py_ + +**Pythons**: CPython 2.6, 2.7, 3.3, 3.4, PyPy-2.3 + +**Operating systems**: Linux, Windows, OSX, Unix + +**Requirements**: setuptools_ or Distribute_ + +**Installers**: ``easy_install`` and ``pip`` + +**hg repository**: https://bitbucket.org/hpk42/py + +easy install or pip ``py`` +----------------------------- + +Both `Distribute`_ and setuptools_ provide the ``easy_install`` +installation tool with which you can type into a command line window:: + + easy_install -U py + +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:: + + As of version 1.4 py does not contain py.test anymore - you + need to install the new `pytest`_ distribution. + +.. _pytest: http://pytest.org + +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 + +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/ + +activating a checkout with setuptools +-------------------------------------------- + +With a working `Distribute`_ or setuptools_ installation you can type:: + + python setup.py develop + +in order to work inline with the tools and the lib of your checkout. + +.. _`no-setuptools`: + +.. _`directly use a checkout`: + +.. _`setuptools`: http://pypi.python.org/pypi/setuptools + + +Mailing list and issue tracker +-------------------------------------- + +- `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/py/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 diff --git a/testing/web-platform/tests/tools/py/doc/io.txt b/testing/web-platform/tests/tools/py/doc/io.txt new file mode 100644 index 000000000..c11308a6d --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/io.txt @@ -0,0 +1,59 @@ +======= +py.io +======= + + +The 'py' lib provides helper classes for capturing IO during +execution of a program. + +IO Capturing examples +=============================================== + +``py.io.StdCapture`` +--------------------------- + +Basic Example:: + + >>> import py + >>> capture = py.io.StdCapture() + >>> print "hello" + >>> out,err = capture.reset() + >>> out.strip() == "hello" + True + +For calling functions you may use a shortcut:: + + >>> import py + >>> def f(): print "hello" + >>> res, out, err = py.io.StdCapture.call(f) + >>> out.strip() == "hello" + True + +``py.io.StdCaptureFD`` +--------------------------- + +If you also want to capture writes to the stdout/stderr +filedescriptors you may invoke:: + + >>> import py, sys + >>> capture = py.io.StdCaptureFD(out=False, in_=False) + >>> sys.stderr.write("world") + >>> 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: + diff --git a/testing/web-platform/tests/tools/py/doc/links.inc b/testing/web-platform/tests/tools/py/doc/links.inc new file mode 100644 index 000000000..9bcfe5cf8 --- /dev/null +++ b/testing/web-platform/tests/tools/py/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/ diff --git a/testing/web-platform/tests/tools/py/doc/log.txt b/testing/web-platform/tests/tools/py/doc/log.txt new file mode 100644 index 000000000..ca60fcac2 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/log.txt @@ -0,0 +1,208 @@ +.. role:: code(literal) +.. role:: file(literal) + +.. XXX figure out how the code literals should be dealt with in sphinx. There is probably something builtin. + +======================================== +py.log documentation and musings +======================================== + + +Foreword +======== + +This document is an attempt to briefly state the actual specification of the +:code:`py.log` module. It was written by Francois Pinard and also contains +some ideas for enhancing the py.log facilities. + +NOTE that :code:`py.log` is subject to refactorings, it may change with +the next release. + +This document is meant to trigger or facilitate discussions. It shamelessly +steals from the `Agile Testing`__ comments, and from other sources as well, +without really trying to sort them out. + +__ http://agiletesting.blogspot.com/2005/06/keyword-based-logging-with-py-library.html + + +Logging organisation +==================== + +The :code:`py.log` module aims a niche comparable to the one of the +`logging module`__ found within the standard Python distributions, yet +with much simpler paradigms for configuration and usage. + +__ http://www.python.org/doc/2.4.2/lib/module-logging.html + +Holger Krekel, the main :code:`py` library developer, introduced +the idea of keyword-based logging and the idea of logging *producers* and +*consumers*. A log producer is an object used by the application code +to send messages to various log consumers. When you create a log +producer, you define a set of keywords that are then used to both route +the logging messages to consumers, and to prefix those messages. + +In fact, each log producer has a few keywords associated with it for +identification purposes. These keywords form a tuple of strings, and +may be used to later retrieve a particular log producer. + +A log producer may (or may not) be associated with a log consumer, meant +to handle log messages in particular ways. The log consumers can be +``STDOUT``, ``STDERR``, log files, syslog, the Windows Event Log, user +defined functions, etc. (Yet, logging to syslog or to the Windows Event +Log is only future plans for now). A log producer has never more than +one consumer at a given time, but it is possible to dynamically switch +a producer to use another consumer. On the other hand, a single log +consumer may be associated with many producers. + +Note that creating and associating a producer and a consumer is done +automatically when not otherwise overriden, so using :code:`py` logging +is quite comfortable even in the smallest programs. More typically, +the application programmer will likely design a hierarchy of producers, +and will select keywords appropriately for marking the hierarchy tree. +If a node of the hierarchical tree of producers has to be divided in +sub-trees, all producers in the sub-trees share, as a common prefix, the +keywords of the node being divided. In other words, we go further down +in the hierarchy of producers merely by adding keywords. + +Using the py.log library +================================ + +To use the :code:`py.log` library, the user must import it into a Python +application, create at least one log producer and one log consumer, have +producers and consumers associated, and finally call the log producers +as needed, giving them log messages. + +Importing +--------- + +Once the :code:`py` library is installed on your system, a mere:: + + import py + +holds enough magic for lazily importing the various facilities of the +:code:`py` library when they are first needed. This is really how +:code:`py.log` is made available to the application. For example, after +the above ``import py``, one may directly write ``py.log.Producer(...)`` +and everything should work fine, the user does not have to worry about +specifically importing more modules. + +Creating a producer +------------------- + +There are three ways for creating a log producer instance: + + + As soon as ``py.log`` is first evaluated within an application + program, a default log producer is created, and made available under + the name ``py.log.default``. The keyword ``default`` is associated + with that producer. + + + The ``py.log.Producer()`` constructor may be explicitly called + for creating a new instance of a log producer. That constructor + accepts, as an argument, the keywords that should be associated with + that producer. Keywords may be given either as a tuple of keyword + strings, or as a single space-separated string of keywords. + + + Whenever an attribute is *taken* out of a log producer instance, + for the first time that attribute is taken, a new log producer is + created. The keywords associated with that new producer are those + of the initial producer instance, to which is appended the name of + the attribute being taken. + +The last point is especially useful, as it allows using log producers +without further declarations, merely creating them *on-the-fly*. + +Creating a consumer +------------------- + +There are many ways for creating or denoting a log consumer: + + + A default consumer exists within the ``py.log`` facilities, which + has the effect of writing log messages on the Python standard output + stream. That consumer is associated at the very top of the producer + hierarchy, and as such, is called whenever no other consumer is + found. + + + The notation ``py.log.STDOUT`` accesses a log consumer which writes + log messages on the Python standard output stream. + + + The notation ``py.log.STDERR`` accesses a log consumer which writes + log messages on the Python standard error stream. + + + The ``py.log.File()`` constructor accepts, as argument, either a file + already opened in write mode or any similar file-like object, and + creates a log consumer able to write log messages onto that file. + + + The ``py.log.Path()`` constructor accepts a file name for its first + argument, and creates a log consumer able to write log messages into + that file. The constructor call accepts a few keyword parameters: + + + ``append``, which is ``False`` by default, may be used for + opening the file in append mode instead of write mode. + + + ``delayed_create``, which is ``False`` by default, maybe be used + for opening the file at the latest possible time. Consequently, + the file will not be created if it did not exist, and no actual + log message gets written to it. + + + ``buffering``, which is 1 by default, is used when opening the + file. Buffering can be turned off by specifying a 0 value. The + buffer size may also be selected through this argument. + + + Any user defined function may be used for a log consumer. Such a + function should accept a single argument, which is the message to + write, and do whatever is deemed appropriate by the programmer. + When the need arises, this may be an especially useful and flexible + feature. + + + The special value ``None`` means no consumer at all. This acts just + like if there was a consumer which would silently discard all log + messages sent to it. + +Associating producers and consumers +----------------------------------- + +Each log producer may have at most one log consumer associated with +it. A log producer gets associated with a log consumer through a +``py.log.setconsumer()`` call. That function accepts two arguments, +the first identifying a producer (a tuple of keyword strings or a single +space-separated string of keywords), the second specifying the precise +consumer to use for that producer. Until this function is called for a +producer, that producer does not have any explicit consumer associated +with it. + +Now, the hierarchy of log producers establishes which consumer gets used +whenever a producer has no explicit consumer. When a log producer +has no consumer explicitly associated with it, it dynamically and +recursively inherits the consumer of its parent node, that is, that node +being a bit closer to the root of the hierarchy. In other words, the +rightmost keywords of that producer are dropped until another producer +is found which has an explicit consumer. A nice side-effect is that, +by explicitly associating a consumer with a producer, all consumer-less +producers which appear under that producer, in the hierarchy tree, +automatically *inherits* that consumer. + +Writing log messages +-------------------- + +All log producer instances are also functions, and this is by calling +them that log messages are generated. Each call to a producer object +produces the text for one log entry, which in turn, is sent to the log +consumer for that producer. + +The log entry displays, after a prefix identifying the log producer +being used, all arguments given in the call, converted to strings and +space-separated. (This is meant by design to be fairly similar to what +the ``print`` statement does in Python). The prefix itself is made up +of a colon-separated list of keywords associated with the producer, the +whole being set within square brackets. + +Note that the consumer is responsible for adding the newline at the end +of the log entry. That final newline is not part of the text for the +log entry. + +.. Other details +.. ------------- +.. XXX: fill in details +.. + Should speak about pickle-ability of :code:`py.log`. +.. +.. + What is :code:`log.get` (in :file:`logger.py`)? diff --git a/testing/web-platform/tests/tools/py/doc/misc.txt b/testing/web-platform/tests/tools/py/doc/misc.txt new file mode 100644 index 000000000..8c3c0b3f7 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/misc.txt @@ -0,0 +1,93 @@ +==================================== +Miscellaneous features of the py lib +==================================== + +Mapping the standard python library into py +=========================================== + +The ``py.std`` object allows lazy access to +standard library modules. For example, to get to the print-exception +functionality of the standard library you can write:: + + py.std.traceback.print_exc() + +without having to do anything else than the usual ``import py`` +at the beginning. You can access any other top-level standard +library module this way. This means that you will only trigger +imports of modules that are actually needed. Note that no attempt +is made to import submodules. + +Support for interaction with system utilities/binaries +====================================================== + +Currently, the py lib offers two ways to interact with +system executables. ``py.process.cmdexec()`` invokes +the shell in order to execute a string. The other +one, ``py.path.local``'s 'sysexec()' method lets you +directly execute a binary. + +Both approaches will raise an exception in case of a return- +code other than 0 and otherwise return the stdout-output +of the child process. + +The shell based approach +------------------------ + +You can execute a command via your system shell +by doing something like:: + + out = py.process.cmdexec('ls -v') + +However, the ``cmdexec`` approach has a few shortcomings: + +- it relies on the underlying system shell +- it neccessitates shell-escaping for expressing arguments +- it does not easily allow to "fix" the binary you want to run. +- it only allows to execute executables from the local + filesystem + +.. _sysexec: + +local paths have ``sysexec`` +---------------------------- + +In order to synchronously execute an executable file you +can use ``sysexec``:: + + binsvn.sysexec('ls', 'http://codespeak.net/svn') + +where ``binsvn`` is a path that points to the ``svn`` commandline +binary. Note that this function does not offer any shell-escaping +so you have to pass in already separated arguments. + +finding an executable local path +-------------------------------- + +Finding an executable is quite different on multiple platforms. +Currently, the ``PATH`` environment variable based search on +unix platforms is supported:: + + py.path.local.sysfind('svn') + +which returns the first path whose ``basename`` matches ``svn``. +In principle, `sysfind` deploys platform specific algorithms +to perform the search. On Windows, for example, it may look +at the registry (XXX). + +To make the story complete, we allow to pass in a second ``checker`` +argument that is called for each found executable. For example, if +you have multiple binaries available you may want to select the +right version:: + + def mysvn(p): + """ check that the given svn binary has version 1.1. """ + line = p.execute('--version'').readlines()[0] + if line.find('version 1.1'): + return p + binsvn = py.path.local.sysfind('svn', checker=mysvn) + + +Cross-Python Version compatibility helpers +============================================= + +The ``py.builtin`` namespace provides a number of helpers that help to write python code compatible across Python interpreters, mainly Python2 and Python3. Type ``help(py.builtin)`` on a Python prompt for a the selection of builtins. diff --git a/testing/web-platform/tests/tools/py/doc/path.txt b/testing/web-platform/tests/tools/py/doc/path.txt new file mode 100644 index 000000000..837c1d192 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/path.txt @@ -0,0 +1,260 @@ +======= +py.path +======= + +The 'py' lib provides a uniform high-level api to deal with filesystems +and filesystem-like interfaces: ``py.path``. It aims to offer a central +object to fs-like object trees (reading from and writing to files, adding +files/directories, examining the types and structure, etc.), and out-of-the-box +provides a number of implementations of this API. + +py.path.local - local file system 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 +of course all the functionality is bundled together rather than spread over a +number of modules. + +Example usage, here we use the ``py.test.ensuretemp()`` function to create +a ``py.path.local`` object for us (which wraps a directory): + +.. sourcecode:: pycon + + >>> import py + >>> temppath = py.test.ensuretemp('py.path_documentation') + >>> foopath = temppath.join('foo') # get child 'foo' (lazily) + >>> foopath.check() # check if child 'foo' exists + False + >>> foopath.write('bar') # write some data to it + >>> foopath.check() + True + >>> foopath.read() + 'bar' + >>> foofile = foopath.open() # return a 'real' file object + >>> 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') +by interfacing with a remote server, the second by wrapping a local checkout. +Both allow you to access relatively advanced features such as metadata and +versioning, and both in a way more user-friendly manner than existing other +solutions. + +Some example usage of ``py.path.svnurl``: + +.. sourcecode:: pycon + + .. >>> import py + .. >>> if not py.test.config.option.urlcheck: raise ValueError('skipchunk') + >>> url = py.path.svnurl('http://codespeak.net/svn/py') + >>> info = url.info() + >>> info.kind + 'dir' + >>> firstentry = url.log()[-1] + >>> import time + >>> time.strftime('%Y-%m-%d', time.gmtime(firstentry.date)) + '2004-10-02' + +Example usage of ``py.path.svnwc``: + +.. sourcecode:: pycon + + .. >>> if not py.test.config.option.urlcheck: raise ValueError('skipchunk') + >>> temp = py.test.ensuretemp('py.path_documentation') + >>> wc = py.path.svnwc(temp.join('svnwc')) + >>> wc.checkout('http://codespeak.net/svn/py/dist/py/path/local') + >>> wc.join('local.py').check() + True + +.. _`Subversion`: http://subversion.tigris.org/ + +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 +path object within an application (e.g. from "local" to "svnwc"). +The common set includes functions such as `path.read()` to read all data +from a file, `path.write()` to write data, `path.listdir()` to get a list +of directory entries, `path.check()` to check if a node exists +and is of a particular type, `path.join()` to get +to a (grand)child, `path.visit()` to recursively walk through a node's +children, etc. Only things that are not common on 'normal' filesystems (yet), +such as handling metadata (e.g. the Subversion "properties") require +using specific APIs. + +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. + +.. sourcecode:: pycon + + >>> dirpath = temppath.ensure('testdir', dir=True) + >>> dirpath.join('textfile1.txt').write('foo bar baz') + >>> dirpath.join('textfile2.txt').write('frob bar spam eggs') + >>> subdir = dirpath.ensure('subdir', dir=True) + >>> subdir.join('textfile1.txt').write('foo baz') + >>> subdir.join('textfile2.txt').write('spam eggs spam foo bar spam') + >>> results = [] + >>> for fpath in dirpath.visit('*.txt'): + ... if 'bar' in fpath.read(): + ... results.append(fpath.basename) + >>> results.sort() + >>> results + ['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, +all operations are performed on a string level (so the paths +don't have to exist, either): + +.. sourcecode:: pycon + + >>> p1 = py.path.local('/foo/bar') + >>> p2 = p1.join('baz/qux') + >>> p2 == py.path.local('/foo/bar/baz/qux') + True + >>> sep = py.path.local.sep + >>> p2.relto(p1).replace(sep, '/') # os-specific path sep in the string + 'baz/qux' + >>> p2.bestrelpath(p1).replace(sep, '/') + '../..' + >>> p2.join(p2.bestrelpath(p1)) == p1 + True + >>> p3 = p1 / 'baz/qux' # the / operator allows joining, too + >>> p2 == p3 + True + >>> p4 = p1 + ".py" + >>> p4.basename == "bar.py" + True + >>> p4.ext == ".py" + True + >>> p4.purebasename == "bar" + True + +This should be possible on every implementation of ``py.path``, so +regardless of whether the implementation wraps a UNIX filesystem, a Windows +one, or a database or object tree, these functions should be available (each +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.: + +.. sourcecode:: pycon + + >>> file1 = temppath.join('file1') + >>> file1.check() # does it exist? + False + >>> file1 = file1.ensure(file=True) # 'touch' the file + >>> file1.check() + True + >>> file1.check(dir=True) # is it a dir? + False + >>> file1.check(file=True) # or a file? + True + >>> file1.check(ext='.txt') # check the extension + False + >>> textfile = temppath.ensure('text.txt', file=True) + >>> textfile.check(ext='.txt') + True + >>> file1.check(basename='file1') # we can use all the path's properties here + 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: + +.. sourcecode:: pycon + + .. >>> if not py.test.config.option.urlcheck: raise ValueError('skipchunk') + >>> wc.propget('foo') + '' + >>> wc.propset('foo', 'bar') + >>> wc.propget('foo') + 'bar' + >>> len(wc.status().prop_modified) # our own props + 1 + >>> msg = wc.revert() # roll back our changes + >>> len(wc.status().prop_modified) + 0 + +SVN authentication +---------------------------- + +Some uncommon functionality can also be provided as extensions, such as SVN +authentication: + +.. sourcecode:: pycon + + .. >>> if not py.test.config.option.urlcheck: raise ValueError('skipchunk') + >>> auth = py.path.SvnAuth('anonymous', 'user', cache_auth=False, + ... interactive=False) + >>> wc.auth = auth + >>> wc.update() # this should work + >>> path = wc.ensure('thisshouldnotexist.txt') + >>> try: + ... path.commit('testing') + ... except py.process.cmdexec.Error, e: + ... pass + >>> 'authorization failed' in str(e) + True + +Known problems / limitations +=================================== + +* The SVN path objects require the "svn" command line, + there is currently no support for python bindings. + Parsing the svn output can lead to problems, particularly + regarding if you have a non-english "locales" setting. + +* While the path objects basically work on windows, + there is no attention yet on making unicode paths + work or deal with the famous "8.3" filename issues. + + diff --git a/testing/web-platform/tests/tools/py/doc/style.css b/testing/web-platform/tests/tools/py/doc/style.css new file mode 100644 index 000000000..1faf762c7 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/style.css @@ -0,0 +1,1044 @@ +body,body.editor,body.body { + font: 110% "Times New Roman", Arial, Verdana, Helvetica, serif; + background: White; + color: Black; +} + +a, a.reference { + text-decoration: none; +} +a[href]:hover { text-decoration: underline; } + +img { + border: none; + vertical-align: middle; +} + +p, div.text { + text-align: left; + line-height: 1.5em; + margin: 0.5em 0em 0em 0em; +} + + + +p a:active { + color: Red; + background-color: transparent; +} + +p img { + border: 0; + margin: 0; +} + +img.inlinephoto { + padding: 0; + padding-right: 1em; + padding-top: 0.7em; + float: left; +} + +hr { + clear: both; + height: 1px; + color: #8CACBB; + background-color: transparent; +} + + +ul { + line-height: 1.5em; + /*list-style-image: url("bullet.gif"); */ + margin-left: 1.5em; + padding:0; +} + +ol { + line-height: 1.5em; + margin-left: 1.5em; + padding:0; +} + +ul a, ol a { + text-decoration: underline; +} + +dl { +} + +dd { + line-height: 1.5em; + margin-bottom: 1em; +} + +blockquote { + font-family: Times, "Times New Roman", serif; + font-style: italic; + font-size: 120%; +} + +code { + color: Black; + /*background-color: #dee7ec;*/ + /*background-color: #cccccc;*/ +} + +pre { + padding: 1em; + border: 1px dotted #8cacbb; + color: Black; + /* + background-color: #dee7ec; + background-color: #cccccc; + background-color: #dee7ec; + */ + overflow: auto; +} + + +.netscape4 { + display: none; +} + +/* main page styles */ + +/*a[href]:hover { color: black; text-decoration: underline; } +a[href]:link { color: black; text-decoration: underline; } +a[href] { color: black; text-decoration: underline; } +*/ + +span.menu_selected { + color: black; + text-decoration: none; + padding-right: 0.3em; + background-color: #cccccc; +} + + +a.menu { + /*color: #3ba6ec; */ + font: 120% Verdana, Helvetica, Arial, sans-serif; + text-decoration: none; + padding-right: 0.3em; +} + +a.menu[href]:visited, a.menu[href]:link{ + /*color: #3ba6ec; */ + text-decoration: none; +} + +a.menu[href]:hover { + /*color: black;*/ +} + +div#pagetitle{ + /*border-spacing: 20px;*/ + font: 160% Verdana, Helvetica, Arial, sans-serif; + color: #3ba6ec; + vertical-align: middle; + left: 80 px; + padding-bottom: 0.3em; +} + +a.wikicurrent { + font: 100% Verdana, Helvetica, Arial, sans-serif; + color: #3ba6ec; + vertical-align: middle; +} + + +table.body { + border: 0; + /*padding: 0; + border-spacing: 0px; + border-collapse: separate; + */ +} + +td.page-header-left { + padding: 5px; + /*border-bottom: 1px solid #444444;*/ +} + +td.page-header-top { + padding: 0; + + /*border-bottom: 1px solid #444444;*/ +} + +td.sidebar { + padding: 1 0 0 1; +} + +td.sidebar p.classblock { + padding: 0 5 0 5; + margin: 1 1 1 1; + border: 1px solid #444444; + background-color: #eeeeee; +} + +td.sidebar p.userblock { + padding: 0 5 0 5; + margin: 1 1 1 1; + border: 1px solid #444444; + background-color: #eeeeff; +} + +td.content { + padding: 1 5 1 5; + vertical-align: top; + width: 100%; +} + +p.ok-message { + background-color: #22bb22; + padding: 5 5 5 5; + color: white; + font-weight: bold; +} +p.error-message { + background-color: #bb2222; + padding: 5 5 5 5; + color: white; + font-weight: bold; +} + +p:first-child { + margin: 0 ; + padding: 0; +} + +/* style for forms */ +table.form { + padding: 2; + border-spacing: 0px; + border-collapse: separate; +} + +table.form th { + color: #333388; + text-align: right; + vertical-align: top; + font-weight: normal; +} +table.form th.header { + font-weight: bold; + background-color: #eeeeff; + text-align: left; +} + +table.form th.required { + font-weight: bold; +} + +table.form td { + color: #333333; + empty-cells: show; + vertical-align: top; +} + +table.form td.optional { + font-weight: bold; + font-style: italic; +} + +table.form td.html { + color: #777777; +} + +/* style for lists */ +table.list { + border-spacing: 0px; + border-collapse: separate; + vertical-align: top; + padding-top: 0; + width: 100%; +} + +table.list th { + padding: 0 4 0 4; + color: #404070; + background-color: #eeeeff; + border-right: 1px solid #404070; + border-top: 1px solid #404070; + border-bottom: 1px solid #404070; + vertical-align: top; + empty-cells: show; +} +table.list th a[href]:hover { color: #404070 } +table.list th a[href]:link { color: #404070 } +table.list th a[href] { color: #404070 } +table.list th.group { + background-color: #f4f4ff; + text-align: center; + font-size: 120%; +} + +table.list td { + padding: 0 4 0 4; + border: 0 2 0 2; + border-right: 1px solid #404070; + color: #404070; + background-color: white; + vertical-align: top; + empty-cells: show; +} + +table.list tr.normal td { + background-color: white; + white-space: nowrap; +} + +table.list tr.alt td { + background-color: #efefef; + white-space: nowrap; +} + +table.list td:first-child { + border-left: 1px solid #404070; + border-right: 1px solid #404070; +} + +table.list th:first-child { + border-left: 1px solid #404070; + border-right: 1px solid #404070; +} + +table.list tr.navigation th { + text-align: right; +} +table.list tr.navigation th:first-child { + border-right: none; + text-align: left; +} + + +/* style for message displays */ +table.messages { + border-spacing: 0px; + border-collapse: separate; + width: 100%; +} + +table.messages th.header{ + padding-top: 10px; + border-bottom: 1px solid gray; + font-weight: bold; + background-color: white; + color: #707040; +} + +table.messages th { + font-weight: bold; + color: black; + text-align: left; + border-bottom: 1px solid #afafaf; +} + +table.messages td { + font-family: monospace; + background-color: #efefef; + border-bottom: 1px solid #afafaf; + color: black; + empty-cells: show; + border-right: 1px solid #afafaf; + vertical-align: top; + padding: 2 5 2 5; +} + +table.messages td:first-child { + border-left: 1px solid #afafaf; + border-right: 1px solid #afafaf; +} + +/* style for file displays */ +table.files { + border-spacing: 0px; + border-collapse: separate; + width: 100%; +} + +table.files th.header{ + padding-top: 10px; + border-bottom: 1px solid gray; + font-weight: bold; + background-color: white; + color: #707040; +} + +table.files th { + border-bottom: 1px solid #afafaf; + font-weight: bold; + text-align: left; +} + +table.files td { + font-family: monospace; + empty-cells: show; +} + +/* style for history displays */ +table.history { + border-spacing: 0px; + border-collapse: separate; + width: 100%; +} + +table.history th.header{ + padding-top: 10px; + border-bottom: 1px solid gray; + font-weight: bold; + background-color: white; + color: #707040; + font-size: 100%; +} + +table.history th { + border-bottom: 1px solid #afafaf; + font-weight: bold; + text-align: left; + font-size: 90%; +} + +table.history td { + font-size: 90%; + vertical-align: top; + empty-cells: show; +} + + +/* style for class list */ +table.classlist { + border-spacing: 0px; + border-collapse: separate; + width: 100%; +} + +table.classlist th.header{ + padding-top: 10px; + border-bottom: 1px solid gray; + font-weight: bold; + background-color: white; + color: #707040; +} + +table.classlist th { + font-weight: bold; + text-align: left; +} + + +/* style for class help display */ +table.classhelp { + border-spacing: 0px; + border-collapse: separate; + width: 100%; +} + +table.classhelp th { + font-weight: bold; + text-align: left; + color: #707040; +} + +table.classhelp td { + padding: 2 2 2 2; + border: 1px solid black; + text-align: left; + vertical-align: top; + empty-cells: show; +} + + +/* style for "other" displays */ +table.otherinfo { + border-spacing: 0px; + border-collapse: separate; + width: 100%; +} + +table.otherinfo th.header{ + padding-top: 10px; + border-bottom: 1px solid gray; + font-weight: bold; + background-color: white; + color: #707040; +} + +table.otherinfo th { + border-bottom: 1px solid #afafaf; + font-weight: bold; + text-align: left; +} + +input { + border: 1px solid #8cacbb; + color: Black; + background-color: white; + vertical-align: middle; + margin-bottom: 1px; /* IE bug fix */ + padding: 0.1em; +} + +select { + border: 1px solid #8cacbb; + color: Black; + background-color: white; + vertical-align: middle; + margin-bottom: 1px; /* IE bug fix */ + padding: 0.1em; +} + + +a.nonexistent { + color: #FF2222; +} +a.nonexistent:visited { + color: #FF2222; +} +a.external { + color: #AA6600; +} + +/* +dl,ul,ol { + margin-top: 1pt; +} +tt,pre { + font-family: Lucida Console,Courier New,Courier,monotype; + font-size: 12pt; +} +pre.code { + margin-top: 8pt; + margin-bottom: 8pt; + background-color: #FFFFEE; + white-space:pre; + border-style:solid; + border-width:1pt; + border-color:#999999; + color:#111111; + padding:5px; + width:100%; +} +*/ +div.diffold { + background-color: #FFFF80; + border-style:none; + border-width:thin; + width:100%; +} +div.diffnew { + background-color: #80FF80; + border-style:none; + border-width:thin; + width:100%; +} +div.message { + margin-top: 6pt; + background-color: #E8FFE8; + border-style:solid; + border-width:1pt; + border-color:#999999; + color:#440000; + padding:5px; + width:100%; +} +strong.highlight { + background-color: #FFBBBB; +/* as usual, NetScape fucks up with innocent CSS + border-color: #FFAAAA; + border-style: solid; + border-width: 1pt; +*/ +} + +table.navibar { + background-color: #C8C8C8; + border-spacing: 3px; +} +td.navibar { + background-color: #E8E8E8; + vertical-align: top; + text-align: right; + padding: 0px; +} + +a#versioninfo { + color: blue; +} + +div#pagename { + font-size: 140%; + color: blue; + text-align: center; + font-weight: bold; + background-color: white; + padding: 0 ; +} + +a.wikiaction, input.wikiaction { + color: black; + text-decoration: None; + text-align: center; + color: black; + /*border: 1px solid #3ba6ec; */ + margin: 4px; + padding: 5; + padding-bottom: 0; + white-space: nowrap; +} + +a.wikiaction[href]:hover { + color: black; + text-decoration: none; + /*background-color: #dddddd; */ +} + + +div.legenditem { + padding-top: 0.5em; + padding-left: 0.3em; +} + +span.wikitoken { + background-color: #eeeeee; +} + + +div#contentspace h1:first-child, div.heading:first-child { + padding-top: 0; + margin-top: 0; +} +div#contentspace h2:first-child { + padding-top: 0; + margin-top: 0; +} + +/* heading and paragraph text */ + +div.heading, h1 { + font-family: Verdana, Helvetica, Arial, sans-serif; + background-color: #58b3ef; + background-color: #FFFFFF; + /*color: #4893cf;*/ + color: black; + padding-top: 1.0em; + padding-bottom:0.2em; + text-align: left; + margin-top: 0em; + /*margin-bottom:8pt;*/ + font-weight: bold; + font-size: 115%; + border-bottom: 1px solid #8CACBB; +} + +h2 { + border-bottom: 1px dotted #8CACBB; +} + + +h1, h2, h3, h4, h5, h6 { + color: Black; + clear: left; + font: 100% Verdana, Helvetica, Arial, sans-serif; + margin: 0; + padding-left: 0em; + padding-top: 1em; + padding-bottom: 0.2em; + /*border-bottom: 1px solid #8CACBB;*/ +} +/* h1,h2 { padding-top: 0; }*/ + + +h1 { font-size: 145%; } +h2 { font-size: 115%; } +h3 { font-size: 105%; } +h4 { font-size: 100%; } +h5 { font-size: 100%; } + +h1 a { text-decoration: None;} + +div.exception { + background-color: #bb2222; + padding: 5 5 5 5; + color: white; + font-weight: bold; +} +pre.exception { + font-size: 110%; + padding: 1em; + border: 1px solid #8cacbb; + color: Black; + background-color: #dee7ec; + background-color: #cccccc; +} + +/* defines for navgiation bar (documentation) */ + + +div.direntry { + padding-top: 0.3em; + padding-bottom: 0.3em; + margin-right: 1em; + font-weight: bold; + background-color: #dee7ec; + font-size: 110%; +} + +div.fileentry { + font-family: Verdana, Helvetica, Arial, sans-serif; + padding-bottom: 0.3em; + white-space: nowrap; + line-height: 150%; +} + +a.fileentry { + white-space: nowrap; +} + + +span.left { + text-align: left; +} +span.right { + text-align: right; +} + +div.navbar { + /*margin: 0;*/ + font-size: 80% /*smaller*/; + font-weight: bold; + text-align: left; + /* position: fixed; */ + top: 100pt; + left: 0pt; /* auto; */ + width: 120pt; + /* right: auto; + right: 0pt; 2em; */ +} + + +div.history a { + /* font-size: 70%; */ +} + +div.wikiactiontitle { + font-weight: bold; +} + +/* REST defines */ + +div.document { + margin: 0; +} + +h1.title { + margin: 0; + margin-bottom: 0.5em; +} + +td.toplist { + vertical-align: top; +} + +img#pyimg { + float: left; + padding-bottom: 1em; +} + +div#navspace { + position: absolute; + font-size: 100%; + width: 150px; + overflow: hidden; /* scroll; */ +} + + +div#errorline { + position: relative; + top: 5px; + float: right; +} + +div#contentspace { + position: absolute; + /* font: 120% "Times New Roman", serif;*/ + font: 110% Verdana, Helvetica, Arial, sans-serif; + left: 170px; + margin-right: 5px; +} + +div#menubar { +/* width: 400px; */ + float: left; +} + +/* for the documentation page */ +div#title{ + + font-size: 110%; + color: black; + + + /*background-color: #dee7ec; + #padding: 5pt; + #padding-bottom: 1em; + #color: black; + border-width: 1pt; + border-style: solid;*/ + +} + +div#docnavlist { + /*background-color: #dee7ec; */ + padding: 5pt; + padding-bottom: 2em; + color: black; + border-width: 1pt; + /*border-style: solid;*/ +} + + +/* text markup */ + +div.listtitle { + color: Black; + clear: left; + font: 120% Verdana, Helvetica, Arial, sans-serif; + margin: 0; + padding-left: 0em; + padding-top: 0em; + padding-bottom: 0.2em; + margin-right: 0.5em; + border-bottom: 1px solid #8CACBB; +} + +div.actionbox h3 { + padding-top: 0; + padding-right: 0.5em; + padding-left: 0.5em; + background-color: #fabf00; + text-align: center; + border: 1px solid black; /* 8cacbb; */ +} + +div.actionbox a { + display: block; + padding-bottom: 0.5em; + padding-top: 0.5em; + margin-left: 0.5em; +} + +div.actionbox a.history { + display: block; + padding-bottom: 0.5em; + padding-top: 0.5em; + margin-left: 0.5em; + font-size: 90%; +} + +div.actionbox { + margin-bottom: 2em; + padding-bottom: 1em; + overflow: hidden; /* scroll; */ +} + +/* taken from docutils (oh dear, a bit senseless) */ +ol.simple, ul.simple { + margin-bottom: 1em } + +ol.arabic { + list-style: decimal } + +ol.loweralpha { + list-style: lower-alpha } + +ol.upperalpha { + list-style: upper-alpha } + +ol.lowerroman { + list-style: lower-roman } + +ol.upperroman { + list-style: upper-roman } + + +/* +:Author: David Goodger +:Contact: goodger@users.sourceforge.net +:date: $Date: 2003/01/22 22:26:48 $ +:version: $Revision: 1.29 $ +:copyright: This stylesheet has been placed in the public domain. + +Default cascading style sheet for the HTML output of Docutils. +*/ +/* +.first { + margin-top: 0 } + +.last { + margin-bottom: 0 } + +a.toc-backref { + text-decoration: none ; + color: black } + +dd { + margin-bottom: 0.5em } + +div.abstract { + margin: 2em 5em } + +div.abstract p.topic-title { + font-weight: bold ; + text-align: center } + +div.attention, div.caution, div.danger, div.error, div.hint, +div.important, div.note, div.tip, div.warning { + margin: 2em ; + border: medium outset ; + padding: 1em } + +div.attention p.admonition-title, div.caution p.admonition-title, +div.danger p.admonition-title, div.error p.admonition-title, +div.warning p.admonition-title { + color: red ; + font-weight: bold ; + font-family: sans-serif } + +div.hint p.admonition-title, div.important p.admonition-title, +div.note p.admonition-title, div.tip p.admonition-title { + font-weight: bold ; + font-family: sans-serif } + +div.dedication { + margin: 2em 5em ; + text-align: center ; + font-style: italic } + +div.dedication p.topic-title { + font-weight: bold ; + font-style: normal } + +div.figure { + margin-left: 2em } + +div.footer, div.header { + font-size: smaller } + +div.system-messages { + margin: 5em } + +div.system-messages h1 { + color: red } + +div.system-message { + border: medium outset ; + padding: 1em } + +div.system-message p.system-message-title { + color: red ; + font-weight: bold } + +div.topic { + margin: 2em } + +h1.title { + text-align: center } + +h2.subtitle { + text-align: center } + +hr { + width: 75% } + +p.caption { + font-style: italic } + +p.credits { + font-style: italic ; + font-size: smaller } + +p.label { + white-space: nowrap } + +p.topic-title { + font-weight: bold } + +pre.address { + margin-bottom: 0 ; + margin-top: 0 ; + font-family: serif ; + font-size: 100% } + +pre.line-block { + font-family: serif ; + font-size: 100% } + +pre.literal-block, pre.doctest-block { + margin-left: 2em ; + margin-right: 2em ; + background-color: #eeeeee } + +span.classifier { + font-family: sans-serif ; + font-style: oblique } + +span.classifier-delimiter { + font-family: sans-serif ; + font-weight: bold } + +span.interpreted { + font-family: sans-serif } + +span.option { + white-space: nowrap } + +span.option-argument { + font-style: italic } + +span.pre { + white-space: pre } + +span.problematic { + color: red } + +table { + margin-top: 0.5em ; + margin-bottom: 0.5em } + +table.citation { + border-left: solid thin gray ; + padding-left: 0.5ex } + +table.docinfo { + margin: 2em 4em } + +table.footnote { + border-left: solid thin black ; + padding-left: 0.5ex } + +td, th { + padding-left: 0.5em ; + padding-right: 0.5em ; + vertical-align: top } + +th.docinfo-name, th.field-name { + font-weight: bold ; + text-align: left ; + white-space: nowrap } + +h1 tt, h2 tt, h3 tt, h4 tt, h5 tt, h6 tt { + font-size: 100% } + +tt { + background-color: #eeeeee } + +ul.auto-toc { + list-style-type: none } +*/ + +div.section { + margin-top: 1.0em ; +} diff --git a/testing/web-platform/tests/tools/py/doc/xml.txt b/testing/web-platform/tests/tools/py/doc/xml.txt new file mode 100644 index 000000000..1022de6e9 --- /dev/null +++ b/testing/web-platform/tests/tools/py/doc/xml.txt @@ -0,0 +1,164 @@ +==================================================== +py.xml: simple pythonic xml/html file generation +==================================================== + +Motivation +========== + +There are a plethora of frameworks and libraries to generate +xml and html trees. However, many of them are large, have a +steep learning curve and are often hard to debug. Not to +speak of the fact that they are frameworks to begin with. + +.. _xist: http://www.livinglogic.de/Python/xist/index.html + +a pythonic object model , please +================================ + +The py lib offers a pythonic way to generate xml/html, based on +ideas from xist_ which `uses python class objects`_ to build +xml trees. However, xist_'s implementation is somewhat heavy +because it has additional goals like transformations and +supporting many namespaces. But its basic idea is very easy. + +.. _`uses python class objects`: http://www.livinglogic.de/Python/xist/Howto.html + +generating arbitrary xml structures +----------------------------------- + +With ``py.xml.Namespace`` you have the basis +to generate custom xml-fragments on the fly:: + + class ns(py.xml.Namespace): + "my custom xml namespace" + doc = ns.books( + ns.book( + ns.author("May Day"), + ns.title("python for java programmers"),), + ns.book( + ns.author("why"), + ns.title("Java for Python programmers"),), + publisher="N.N", + ) + print doc.unicode(indent=2).encode('utf8') + +will give you this representation:: + + <books publisher="N.N"> + <book> + <author>May Day</author> + <title>python for java programmers</title></book> + <book> + <author>why</author> + <title>Java for Python programmers</title></book></books> + +In a sentence: positional arguments are child-tags and +keyword-arguments are attributes. + +On a side note, you'll see that the unicode-serializer +supports a nice indentation style which keeps your generated +html readable, basically through emulating python's white +space significance by putting closing-tags rightmost and +almost invisible at first glance :-) + +basic example for generating html +--------------------------------- + +Consider this example:: + + from py.xml import html # html namespace + + paras = "First Para", "Second para" + + doc = html.html( + html.head( + html.meta(name="Content-Type", value="text/html; charset=latin1")), + html.body( + [html.p(p) for p in paras])) + + print unicode(doc).encode('latin1') + +Again, tags are objects which contain tags and have attributes. +More exactly, Tags inherit from the list type and thus can be +manipulated as list objects. They additionally support a default +way to represent themselves as a serialized unicode object. + +If you happen to look at the py.xml implementation you'll +note that the tag/namespace implementation consumes some 50 lines +with another 50 lines for the unicode serialization code. + +CSS-styling your html Tags +-------------------------- + +One aspect where many of the huge python xml/html generation +frameworks utterly fail is a clean and convenient integration +of CSS styling. Often, developers are left alone with keeping +CSS style definitions in sync with some style files +represented as strings (often in a separate .css file). Not +only is this hard to debug but the missing abstractions make +it hard to modify the styling of your tags or to choose custom +style representations (inline, html.head or external). Add the +Browers usual tolerance of messyness and errors in Style +references and welcome to hell, known as the domain of +developing web applications :-) + +By contrast, consider this CSS styling example:: + + class my(html): + "my initial custom style" + class body(html.body): + style = html.Style(font_size = "120%") + + class h2(html.h2): + style = html.Style(background = "grey") + + class p(html.p): + style = html.Style(font_weight="bold") + + doc = my.html( + my.head(), + my.body( + my.h2("hello world"), + my.p("bold as bold can") + ) + ) + + print doc.unicode(indent=2) + +This will give you a small'n mean self contained +represenation by default:: + + <html> + <head/> + <body style="font-size: 120%"> + <h2 style="background: grey">hello world</h2> + <p style="font-weight: bold">bold as bold can</p></body></html> + +Most importantly, note that the inline-styling is just an +implementation detail of the unicode serialization code. +You can easily modify the serialization to put your styling into the +``html.head`` or in a separate file and autogenerate CSS-class +names or ids. + +Hey, you could even write tests that you are using correct +styles suitable for specific browser requirements. Did i mention +that the ability to easily write tests for your generated +html and its serialization could help to develop _stable_ user +interfaces? + +More to come ... +---------------- + +For now, i don't think we should strive to offer much more +than the above. However, it is probably not hard to offer +*partial serialization* to allow generating maybe hundreds of +complex html documents per second. Basically we would allow +putting callables both as Tag content and as values of +attributes. A slightly more advanced Serialization would then +produce a list of unicode objects intermingled with callables. +At HTTP-Request time the callables would get called to +complete the probably request-specific serialization of +your Tags. Hum, it's probably harder to explain this than to +actually code it :-) + +.. _`py.test`: test/index.html |
