[py-svn] r7040 - py/dist/doc
hpk at codespeak.net
hpk at codespeak.net
Tue Oct 19 20:24:33 CEST 2004
Author: hpk
Date: Tue Oct 19 20:24:31 2004
New Revision: 7040
Modified:
py/dist/doc/coding-style.txt
py/dist/doc/index.txt
py/dist/doc/test.txt
py/dist/doc/why_py.txt
Log:
- added some more documentation about py.test features
- improved coding-style
- a reference to AMKs blog about some python standard
library issues.
- lots of little fixes and improvements
Modified: py/dist/doc/coding-style.txt
==============================================================================
--- py/dist/doc/coding-style.txt (original)
+++ py/dist/doc/coding-style.txt Tue Oct 19 20:24:31 2004
@@ -5,16 +5,19 @@
.. contents::
.. sectnum::
-First of all, if you haven't already read it, read
-the `PEP 8 Style Guide for Python Code`_ which, if in doubt,
-describes the policy for the py lib.
+Honour PEP 8: Style Guide for Python Code
+-----------------------------------------
-Naming and environment
-----------------------
+First of all, if you haven't already read it, read the `PEP 8
+Style Guide for Python Code`_ which, if in doubt, serves as
+the default coding-style for the py lib.
-- directories/modules/namespaces are always **lowercase**
+Naming
+------
-- classes and Exceptions are often **CamelCase**
+- directories, modules and namespaces are always **lowercase**
+
+- classes and especially Exceptions are most often **CamelCase**
- never use plural names in directory and file names
@@ -24,26 +27,37 @@
- it's appreciated if you manage to name files in a directory
so that tab-completion on the shell level is as easy as possible.
+
Committing
----------
+- adding features requires adding appropriate tests.
+
+- bug fixes should be encoded in a test before being fixed.
+
- write telling log messages because several people
- are reading the diffs, an we will have a search facility
- over the py lib's repo.
+ will read your diffs, an we will have a search facility
+ over the py lib's subversion repository.
- if you add ``.txt`` or ``.py`` files to the repository then
- please make sure you have 'svn:eol-style' set to native.
+ please make sure you have ``svn:eol-style`` set to native.
which allows checkin/checkout in native line-ending format.
-Test conventions
-----------------
+Miscellaneous
+-------------
-- adding features requires adding appropriate tests.
- Tests are the insurance that your code will be maintained
+- Tests are the insurance that your code will be maintained
further and survives major releases.
-- Try to put the tests close to the tested code, don't clutter
- directories.
+- Try to put the tests close to the tested code, don't
+ overload directories with names.
+
+- If you think of exporting new py lib APIs, discuss it first on the
+ `py-dev mailing list`_ and possibly write a chapter in our
+ `future_` book. Communication is considered a key here to make
+ sure that the py lib develops in a consistent way.
.. _test-design: ../devel/testdesign.html
.. _`PEP 8 Style Guide for Python Code`: http://www.python.org/peps/pep-0008.html
+.. _`py-dev mailing list`: http://codespeak.net/mailman/listinfo/py-dev
+.. _`future`: future.html
Modified: py/dist/doc/index.txt
==============================================================================
--- py/dist/doc/index.txt (original)
+++ py/dist/doc/index.txt Tue Oct 19 20:24:31 2004
@@ -6,7 +6,7 @@
versioning, testing and documentation issues - seen
primarily from the perspective of a FOSS (Free and
Open Source) developer. At the same time, or maybe
-just because of that, the py lib is to be very usable
+just because of that, the py lib is very usable
for real life python applications.*
`why what how py?`_ describes a bit of the motivation and background
Modified: py/dist/doc/test.txt
==============================================================================
--- py/dist/doc/test.txt (original)
+++ py/dist/doc/test.txt Tue Oct 19 20:24:31 2004
@@ -70,6 +70,22 @@
in case of the possible failures (*no exception* or *wrong
exception*) the reporter provides you with helpful output.
+automatic collection of tests on all levels
+-------------------------------------------
+
+The automated test (see `collection process`_ for
+implemenetation details) takes care that all
+files with a leading ``test_`` and then every function
+with a leading ``test_`` or ``Test`` in the case of classes
+are collected.
+
+no interference with cmdline utilities
+--------------------------------------
+
+As ``py.test`` mainly operates as a separate cmdline
+tool you can easily have a command line utility and
+some tests in the same file.
+
debug with the ``print`` statement
----------------------------------
@@ -77,6 +93,7 @@
tests. This output is only displayed when the test fails,
otherwise you will not see it.
+
order of execution is guaranteed
--------------------------------
@@ -215,7 +232,8 @@
Note that ``setup_class(TestStateFullThing)`` is called and not
``TestStateFullThing.setup_class()`` which would require you
to insert ``setup_class = classmethod(setup_class)`` to make
-your setup function callable.
+your setup function callable. Did we mention that lazyness
+is a virtue?
The three components of ``py.test``
===================================
@@ -249,19 +267,7 @@
outcome (possibly an exception) and sends it over to the
*reporter* instance.
-
-Configuration
--------------
-
-``py.test`` detects and honours ``pytest.py`` configuration files
-that can stack in your filesystem. The following configuration
-values are currently recognized::
-
- pythonexecutables a sequence of strings which represent
- a python executable, e.g. ('python2.2',)
-
-For configuration values the upmost ``pytest.py`` has the top
-priority. For example, you can specify
+.. _`collection process`:
Collectors and the test collection process
------------------------------------------
@@ -362,8 +368,9 @@
------------------------------
- Items allow total control of executing their contained test
- method. iteminstance.execute() gets called in order to
- execute a test.
+ method. ``iteminstance.execute()`` will get called by the
+ driver in order to actually execute a test. Thus a custom
+ ``execute()`` method can pass arguments to test functions.
- Item.execute() methods can provide custom paramters
(a db-connection, some initialized application entity, whatever)
Modified: py/dist/doc/why_py.txt
==============================================================================
--- py/dist/doc/why_py.txt (original)
+++ py/dist/doc/why_py.txt Tue Oct 19 20:24:31 2004
@@ -45,6 +45,9 @@
can't solve them all at once but you will find that the above
points currently drive the development of the py lib.
+And it seems there are `related thoughts from AMK`_ about
+standard library development.
+
What is the py libs current focus?
==================================
@@ -84,11 +87,11 @@
Another focus are well tested *Path* implementations that
allow to seemlessly work with different backends, currently
a local filesystem and subversion working copies and subversion
-remote URLs. Moreover, it provides an experimental 'extpy'
+remote URLs. Moreover, it provides an experimental ``extpy``
path to address a Python object on a possibly remote filesystem.
-If you ready to grasp more then you may try reading
-about the future_ of the py lib, which reflect the
+If you are ready to grasp more then you may try reading
+about future_ coding goals of the py lib, which reflect the
current developers thoughts and discussions.
How does py development work?
@@ -117,8 +120,7 @@
Oh right, and you should also agree to release your code under
an ``MIT license`` and consequently any other OSI-approved
-license. This is FOSS (an evolving acronym for Free and Open
-Source Software), and we want to have the py lib interopable
+license. This is FOSS [#]_ and we want to have the py lib interopable
with whatever license style you prefer. Copyright generally
stays with the contributors. We are following the
linux-kernel dev-model with this one.
@@ -155,7 +157,8 @@
Schwarzer* and then *Armin Rigo* who contributed important parts.
He and Holger came up with a couple of iterations of the
testing-code that reduced the API to almost nothing: just the
-assert statement and an assert_raises method.
+plain assert statement and a ``py.test.raises`` method to
+check for occuring exceptions.
Now recently, after Holgers `talk at EP2004`_ more people
were interested and there were discussions with *Jim Fulton*,
@@ -182,3 +185,9 @@
.. _future: future.html
.. _`py.test tool and library`: test.html
.. _`py API`: api.html
+.. _`related thoughts from AMK`: http://www.amk.ca/diary/archives/cat_python.html
+
+--
+
+.. [#] FOSS i an evolving acronym for Free and Open Source Software
+
More information about the pytest-commit
mailing list