| OLD | NEW |
| 1 .. _subprocess: | 1 .. _subprocess: |
| 2 | 2 |
| 3 ====================== | 3 ====================== |
| 4 Measuring subprocesses | 4 Measuring subprocesses |
| 5 ====================== | 5 ====================== |
| 6 | 6 |
| 7 :history: 20100224T201800, new for 3.3. | 7 :history: 20100224T201800, new for 3.3. |
| 8 :history: 20100725T211700, updated for 3.4. | 8 :history: 20100725T211700, updated for 3.4. |
| 9 | 9 |
| 10 | 10 |
| (...skipping 10 matching lines...) Expand all Loading... |
| 21 | 21 |
| 22 When using this technique, be sure to set the parallel option to true so that | 22 When using this technique, be sure to set the parallel option to true so that |
| 23 multiple coverage.py runs will each write their data to a distinct file. | 23 multiple coverage.py runs will each write their data to a distinct file. |
| 24 | 24 |
| 25 | 25 |
| 26 Configuring Python for subprocess coverage | 26 Configuring Python for subprocess coverage |
| 27 ------------------------------------------ | 27 ------------------------------------------ |
| 28 | 28 |
| 29 Measuring coverage in subprocesses is a little tricky. When you spawn a | 29 Measuring coverage in subprocesses is a little tricky. When you spawn a |
| 30 subprocess, you are invoking Python to run your program. Usually, to get | 30 subprocess, you are invoking Python to run your program. Usually, to get |
| 31 coverage measurement, you have to use coverage.py to run your program. | 31 coverage measurement, you have to use coverage.py to run your program. Your |
| 32 Your subprocess won't be using coverage.py, so we have to convince Python | 32 subprocess won't be using coverage.py, so we have to convince Python to use |
| 33 to use coverage even when not explicitly invokved. | 33 coverage even when not explicitly invokved. |
| 34 | 34 |
| 35 To do that, we'll configure Python to run a little coverage.py code when it | 35 To do that, we'll configure Python to run a little coverage.py code when it |
| 36 starts. That code will look for an environment variable that tells it to | 36 starts. That code will look for an environment variable that tells it to start |
| 37 start coverage measurement at the start of the process. | 37 coverage measurement at the start of the process. |
| 38 | 38 |
| 39 To arrange all this, you have to do two things: set a value for the | 39 To arrange all this, you have to do two things: set a value for the |
| 40 ``COVERAGE_PROCESS_START`` environment variable, and then configure Python to | 40 ``COVERAGE_PROCESS_START`` environment variable, and then configure Python to |
| 41 invoke :func:`coverage.process_startup` when Python processes start. | 41 invoke :func:`coverage.process_startup` when Python processes start. |
| 42 | 42 |
| 43 How you set ``COVERAGE_PROCESS_START`` depends on the details of how you create | 43 How you set ``COVERAGE_PROCESS_START`` depends on the details of how you create |
| 44 subprocesses. As long as the environment variable is visible in your subprocess
, | 44 subprocesses. As long as the environment variable is visible in your |
| 45 it will work. | 45 subprocess, it will work. |
| 46 | 46 |
| 47 You can configure your Python installation to invoke the ``process_startup`` | 47 You can configure your Python installation to invoke the ``process_startup`` |
| 48 function in two ways: | 48 function in two ways: |
| 49 | 49 |
| 50 #. Create or append to sitecustomize.py to add these lines:: | 50 #. Create or append to sitecustomize.py to add these lines:: |
| 51 | 51 |
| 52 import coverage | 52 import coverage |
| 53 coverage.process_startup() | 53 coverage.process_startup() |
| 54 | 54 |
| 55 #. Create a .pth file in your Python installation containing:: | 55 #. Create a .pth file in your Python installation containing:: |
| 56 | 56 |
| 57 import coverage; coverage.process_startup() | 57 import coverage; coverage.process_startup() |
| 58 | 58 |
| 59 The sitecustomize.py technique is cleaner, but may involve modifying an existing | 59 The sitecustomize.py technique is cleaner, but may involve modifying an |
| 60 sitecustomize.py, since there can be only one. If there is no sitecustomize.py | 60 existing sitecustomize.py, since there can be only one. If there is no |
| 61 already, you can create it in any directory on the Python path. | 61 sitecustomize.py already, you can create it in any directory on the Python |
| 62 path. |
| 62 | 63 |
| 63 The .pth technique seems like a hack, but works, and is documented behavior. | 64 The .pth technique seems like a hack, but works, and is documented behavior. |
| 64 On the plus side, you can create the file with any name you like so you don't | 65 On the plus side, you can create the file with any name you like so you don't |
| 65 have to coordinate with other .pth files. On the minus side, you have to create | 66 have to coordinate with other .pth files. On the minus side, you have to |
| 66 the file in a system-defined directory, so you may need privileges to write it. | 67 create the file in a system-defined directory, so you may need privileges to |
| 68 write it. |
| 69 |
| 70 Note that if you use one of these techniques, you must undo them if you |
| 71 uninstall coverage.py, since you will be trying to import it during Python |
| 72 startup. Be sure to remove the change when you uninstall coverage.py, or use a |
| 73 more defensive approach to importing it. |
| OLD | NEW |