diff options
author | Ned Batchelder <ned@nedbatchelder.com> | 2013-09-17 20:15:53 -0400 |
---|---|---|
committer | Ned Batchelder <ned@nedbatchelder.com> | 2013-09-17 20:15:53 -0400 |
commit | bcd89039dd7aba5459a1727c44d1661d0a48a96e (patch) | |
tree | c394f7d613a1cc03758fe6127a1f4163a637554b | |
parent | bb098f20ed64bafd3ca14b265f47f657a4be9d79 (diff) | |
download | python-coveragepy-bcd89039dd7aba5459a1727c44d1661d0a48a96e.tar.gz |
Remove notes about me being available for custom work, and rewrap many paragraphs.
-rw-r--r-- | doc/api.rst | 4 | ||||
-rw-r--r-- | doc/branch.rst | 14 | ||||
-rw-r--r-- | doc/cmd.rst | 14 | ||||
-rw-r--r-- | doc/config.rst | 33 | ||||
-rw-r--r-- | doc/contributing.rst | 8 | ||||
-rw-r--r-- | doc/excluding.rst | 12 | ||||
-rw-r--r-- | doc/faq.rst | 9 | ||||
-rw-r--r-- | doc/index.rst | 3 | ||||
-rw-r--r-- | doc/install.rst | 15 | ||||
-rw-r--r-- | doc/source.rst | 4 | ||||
-rw-r--r-- | doc/subprocess.rst | 26 | ||||
-rw-r--r-- | doc/trouble.rst | 14 |
12 files changed, 79 insertions, 77 deletions
diff --git a/doc/api.rst b/doc/api.rst index fe59bc2..a43de17 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -13,8 +13,8 @@ Coverage API The API to coverage.py is very simple, contained in a single module called `coverage`. Most of the interface is in a single class, also called -`coverage`. Methods on the coverage object correspond roughly to operations available -in the command line interface. For example, a simple use would be:: +`coverage`. Methods on the coverage object correspond roughly to operations +available in the command line interface. For example, a simple use would be:: import coverage diff --git a/doc/branch.rst b/doc/branch.rst index 13b9dc6..f6b3ac8 100644 --- a/doc/branch.rst +++ b/doc/branch.rst @@ -73,8 +73,8 @@ __ http://ivory.idyll.org/blog Excluding code -------------- -If you have :ref:`excluded code <excluding>`, a condtional will not be -counted as a branch if one of its choices is excluded:: +If you have :ref:`excluded code <excluding>`, a condtional will not be counted +as a branch if one of its choices is excluded:: def only_one_choice(x): if x: @@ -84,8 +84,8 @@ counted as a branch if one of its choices is excluded:: # x is always true. blah3() -Because the ``else`` clause is excluded, the ``if`` only has one possible -next line, so it isn't considered a branch at all. +Because the ``else`` clause is excluded, the ``if`` only has one possible next +line, so it isn't considered a branch at all. Structurally partial branches @@ -115,6 +115,6 @@ pragma:: break Here the while loop will never complete because the break will always be taken -at some point. Coverage.py can't work that out on its own, but the -"no branch" pragma indicates that the branch is known to be partial, and -the line is not flagged. +at some point. Coverage.py can't work that out on its own, but the "no branch" +pragma indicates that the branch is known to be partial, and the line is not +flagged. diff --git a/doc/cmd.rst b/doc/cmd.rst index 6b1d15d..81a8fbe 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -168,9 +168,9 @@ coverage can combine multiple files into one for reporting. Use the ``-p`` flag during execution to append distinguishing information to the .coverage data file name. -Once you have created a number of these files, you can copy them all to a single -directory, and use the **combine** command to combine them into one .coverage -data file:: +Once you have created a number of these files, you can copy them all to a +single directory, and use the **combine** command to combine them into one +.coverage data file:: $ coverage combine @@ -308,10 +308,10 @@ generating unchanged pages, making the process faster. Text annotation --------------- -The **annotate** command produces a text annotation of your source code. With a -``-d`` argument specifying an output directory, each Python file becomes a text -file in that directory. Without ``-d``, the files are written into the same -directories as the original Python files. +The **annotate** command produces a text annotation of your source code. With +a ``-d`` argument specifying an output directory, each Python file becomes a +text file in that directory. Without ``-d``, the files are written into the +same directories as the original Python files. Coverage status for each line of source is indicated with a character prefix:: diff --git a/doc/config.rst b/doc/config.rst index f6d8f1f..b74e9f4 100644 --- a/doc/config.rst +++ b/doc/config.rst @@ -21,9 +21,9 @@ sub-processes. See :ref:`subprocess` for more details. The default name for configuration files is ``.coveragerc``, in the same directory coverage.py is being run in. Most of the settings in the -configuration file are tied to your source code and how it should be -measured, so it should be stored with your source, and checked into -source control, rather than put in your home directory. +configuration file are tied to your source code and how it should be measured, +so it should be stored with your source, and checked into source control, +rather than put in your home directory. Syntax @@ -114,8 +114,8 @@ Try this if you get seemingly impossible results. [paths] ------- -The entries in this section are lists of file paths that should be -considered equivalent when combining data from different machines:: +The entries in this section are lists of file paths that should be considered +equivalent when combining data from different machines:: [paths] source = @@ -123,15 +123,14 @@ considered equivalent when combining data from different machines:: /jenkins/build/*/src c:\myproj\src -The names of the entries are ignored, you may choose any name that -you like. The value is a lists of strings. When combining data -with the ``combine`` command, two file paths will be combined -if they start with paths from the same list. +The names of the entries are ignored, you may choose any name that you like. +The value is a lists of strings. When combining data with the ``combine`` +command, two file paths will be combined if they start with paths from the same +list. -The first value must be an actual file path on the machine where -the reporting will happen, so that source code can be found. -The other values can be file patterns to match against the paths -of collected data. +The first value must be an actual file path on the machine where the reporting +will happen, so that source code can be found. The other values can be file +patterns to match against the paths of collected data. See :ref:`cmd_combining` for more information. @@ -163,11 +162,11 @@ you are replacing all the partial branch regexes so you'll need to also supply the "pragma: no branch" regex if you still want to use it. ``precision`` (integer): the number of digits after the decimal point to -display for reported coverage percentages. The default is 0, displaying -for example "87%". A value of 2 will display percentages like "87.32%". +display for reported coverage percentages. The default is 0, displaying for +example "87%". A value of 2 will display percentages like "87.32%". -``show_missing`` (boolean, default False): when running a summary report, -show missing lines. See :ref:`cmd_summary` for more information. +``show_missing`` (boolean, default False): when running a summary report, show +missing lines. See :ref:`cmd_summary` for more information. .. _config_html: diff --git a/doc/contributing.rst b/doc/contributing.rst index 6c422b5..88c99a9 100644 --- a/doc/contributing.rst +++ b/doc/contributing.rst @@ -104,8 +104,8 @@ The tests are written as standard unittest-style tests, and are run with (and so on...) Tox runs the complete test suite twice for each version of Python you have -installed. The first run uses the Python implementation of the trace -function, the second uses the C implementation. +installed. The first run uses the Python implementation of the trace function, +the second uses the C implementation. To limit tox to just a few versions of Python, use the ``-e`` switch:: @@ -115,8 +115,8 @@ To run just a few tests, you can use nose test selector syntax:: $ tox tests.test_misc:SetupPyTest.test_metadata -This looks in `tests/test_misc.py` to find the `SetupPyTest` class, and runs the -`test_metadata` test method. +This looks in `tests/test_misc.py` to find the `SetupPyTest` class, and runs +the `test_metadata` test method. Of course, run all the tests on every version of Python you have, before submitting a change. diff --git a/doc/excluding.rst b/doc/excluding.rst index f1262c3..31e8e9b 100644 --- a/doc/excluding.rst +++ b/doc/excluding.rst @@ -39,8 +39,8 @@ function is not reported as missing:: return "<MyObject>" Excluded code is executed as usual, and its execution is recorded in the -coverage data as usual. When producing reports though, coverage excludes it from -the list of missing code. +coverage data as usual. When producing reports though, coverage excludes it +from the list of missing code. Branch coverage @@ -57,8 +57,8 @@ counted as a branch if one of its choices is excluded:: # x is always true. blah3() -Because the ``else`` clause is excluded, the ``if`` only has one possible -next line, so it isn't considered a branch at all. +Because the ``else`` clause is excluded, the ``if`` only has one possible next +line, so it isn't considered a branch at all. Advanced exclusion @@ -70,8 +70,8 @@ expressions. Using :ref:`configuration files <config>` or the coverage often-used constructs to exclude that can be matched with a regex. You can exclude them all at once without littering your code with exclusion pragmas. -For example, you might decide that __repr__ functions are usually only used -in debugging code, and are uninteresting to test themselves. You could exclude +For example, you might decide that __repr__ functions are usually only used in +debugging code, and are uninteresting to test themselves. You could exclude all of them by adding a regex to the exclusion list:: [report] diff --git a/doc/faq.rst b/doc/faq.rst index 6b0c4af..78db591 100644 --- a/doc/faq.rst +++ b/doc/faq.rst @@ -26,9 +26,9 @@ the :ref:`command line <cmd>` to create the reports you need from that data. **Q: Why do unexecutable lines show up as executed?** -Usually this is because you've updated your code and run coverage on it -again without erasing the old data. Coverage records line numbers executed, so -the old data may have recorded a line number which has since moved, causing +Usually this is because you've updated your code and run coverage on it again +without erasing the old data. Coverage records line numbers executed, so the +old data may have recorded a line number which has since moved, causing coverage to claim a line has been executed which cannot be. If you are using the ``-x`` command line action, it doesn't erase first by @@ -98,8 +98,7 @@ Announcements of new coverage.py releases are sent to the .. _coveragepy-announce: http://groups.google.com/group/coveragepy-announce `I can be reached`__ in a number of ways, I'm happy to answer questions about -using coverage.py. I'm also available hourly for consultation or custom -development. +using coverage.py. __ http://nedbatchelder.com/site/aboutned.html diff --git a/doc/index.rst b/doc/index.rst index ed163b8..cb8d885 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -140,8 +140,7 @@ Bitbucket also hosts the `code repository`_. .. _code repository: http://bitbucket.org/ned/coveragepy `I can be reached`_ in a number of ways. I'm happy to answer questions about -using coverage.py. I'm also available hourly for consultation or custom -development. +using coverage.py. .. _I can be reached: http://nedbatchelder.com/site/aboutned.html diff --git a/doc/install.rst b/doc/install.rst index 9539093..0a98e12 100644 --- a/doc/install.rst +++ b/doc/install.rst @@ -48,8 +48,9 @@ or even:: Installing from source ---------------------- -Coverage.py includes a C extension for speed. If you are installing from source, -you may need to install the python-dev support files, for example with:: +Coverage.py includes a C extension for speed. If you are installing from +source, you may need to install the python-dev support files, for example +with:: $ sudo apt-get install python-dev @@ -58,9 +59,9 @@ Installing on Windows --------------------- For Windows, kits are provided on the `PyPI page`__ for different versions of -Python and different CPU architectures. These kits require that `setuptools`_ be -installed as a pre-requisite, but otherwise are self-contained. They have the -C extension pre-compiled so there's no need to worry about compilers. +Python and different CPU architectures. These kits require that `setuptools`_ +be installed as a pre-requisite, but otherwise are self-contained. They have +the C extension pre-compiled so there's no need to worry about compilers. .. __: coverage_pypi_ @@ -68,8 +69,8 @@ C extension pre-compiled so there's no need to worry about compilers. Checking the installation ------------------------- -If all went well, you should be able to open a command prompt, and see -coverage installed properly:: +If all went well, you should be able to open a command prompt, and see coverage +installed properly:: $ coverage --version Coverage.py, version 3.6. http://nedbatchelder.com/code/coverage diff --git a/doc/source.rst b/doc/source.rst index aafb976..ec9994b 100644 --- a/doc/source.rst +++ b/doc/source.rst @@ -25,8 +25,8 @@ Execution When running your code, the ``coverage run`` command will by default measure all code, unless it is part of the Python standard library. -You can specify source to measure with the ``--source`` command-line switch, -or the ``[run] source`` configuration value. The value is a list of directories +You can specify source to measure with the ``--source`` command-line switch, or +the ``[run] source`` configuration value. The value is a list of directories or package names. If specified, only source inside these directories or packages will be measured. Specifying the source option also enables coverage.py to report on unexecuted files, since it can search the source tree diff --git a/doc/subprocess.rst b/doc/subprocess.rst index 6abee18..a4e759d 100644 --- a/doc/subprocess.rst +++ b/doc/subprocess.rst @@ -28,21 +28,21 @@ Configuring Python for subprocess coverage Measuring coverage in subprocesses is a little tricky. When you spawn a subprocess, you are invoking Python to run your program. Usually, to get -coverage measurement, you have to use coverage.py to run your program. -Your subprocess won't be using coverage.py, so we have to convince Python -to use coverage even when not explicitly invokved. +coverage measurement, you have to use coverage.py to run your program. Your +subprocess won't be using coverage.py, so we have to convince Python to use +coverage even when not explicitly invokved. To do that, we'll configure Python to run a little coverage.py code when it -starts. That code will look for an environment variable that tells it to -start coverage measurement at the start of the process. +starts. That code will look for an environment variable that tells it to start +coverage measurement at the start of the process. To arrange all this, you have to do two things: set a value for the ``COVERAGE_PROCESS_START`` environment variable, and then configure Python to invoke :func:`coverage.process_startup` when Python processes start. How you set ``COVERAGE_PROCESS_START`` depends on the details of how you create -subprocesses. As long as the environment variable is visible in your subprocess, -it will work. +subprocesses. As long as the environment variable is visible in your +subprocess, it will work. You can configure your Python installation to invoke the ``process_startup`` function in two ways: @@ -56,14 +56,16 @@ function in two ways: import coverage; coverage.process_startup() -The sitecustomize.py technique is cleaner, but may involve modifying an existing -sitecustomize.py, since there can be only one. If there is no sitecustomize.py -already, you can create it in any directory on the Python path. +The sitecustomize.py technique is cleaner, but may involve modifying an +existing sitecustomize.py, since there can be only one. If there is no +sitecustomize.py already, you can create it in any directory on the Python +path. The .pth technique seems like a hack, but works, and is documented behavior. On the plus side, you can create the file with any name you like so you don't -have to coordinate with other .pth files. On the minus side, you have to create -the file in a system-defined directory, so you may need privileges to write it. +have to coordinate with other .pth files. On the minus side, you have to +create the file in a system-defined directory, so you may need privileges to +write it. Note that if you use one of these techniques, you must undo them if you uninstall coverage.py, since you will be trying to import it during Python diff --git a/doc/trouble.rst b/doc/trouble.rst index c7693c9..ad82f88 100644 --- a/doc/trouble.rst +++ b/doc/trouble.rst @@ -11,9 +11,9 @@ there are some situations it can't cope with. This page details some known problems, with possible courses of action, and links to coverage.py bug reports with more information. -I would love to :ref:`hear from you <contact>` if you have information about any of -these problems, even just to explain to me why you want them to start working -properly. +I would love to :ref:`hear from you <contact>` if you have information about +any of these problems, even just to explain to me why you want them to start +working properly. If your problem isn't discussed here, you can of course search the `coverage.py bug tracker`_ directly to see if there is some mention of it. @@ -75,7 +75,8 @@ Really obscure things --------------------- * Python 2.5 had a bug (`1569356`_) that could make your program behave - differently when being measured with coverage. This is diagnosed in `issue 51`_. + differently when being measured with coverage. This is diagnosed in + `issue 51`_. .. _issue 51: http://bitbucket.org/ned/coveragepy/issue/51/turbogears-15-test-failing-with-coverage .. _1569356: http://bugs.python.org/issue1569356 @@ -84,5 +85,6 @@ Really obscure things Still having trouble? --------------------- -If your problem isn't mentioned here, and isn't already reported in the `coverage.py bug tracker`_, -please :ref:`get in touch with me <contact>`, we'll figure out a solution. +If your problem isn't mentioned here, and isn't already reported in the +`coverage.py bug tracker`_, please :ref:`get in touch with me <contact>`, +we'll figure out a solution. |