Estimate Asymptotic Runtime Complexity from Bytecode executions
Project description
The Python Performance Analysis Library (py-pal) is a profiling tool for the Python programming language. Further details can be found in the documentation at https://py-pal.readthedocs.io.
Installation
Requirements
- An installation of the CPython implementation of the Python programming language of version greater or equal to 3.7
- A compiler for the C/C++ programming language:
- On Microsoft Windows, we use the Buildtools für Visual Studio 2019:
https://visualstudio.microsoft.com/de/thank-you-downloading-visual-studio/?sku=BuildTools&rel=16
On Linux, any C compiler supported by Cython e.g. g++
Install py-pal via pip by running:
This project requires CPython and a C compiler to run. Install CPython >= 3.7, then install py-pal by running:
pip install py-pal
or
python -m pip install py-pal
Development Environment
To set up an environment for developing the py-pal module, the requirements mentioned in the section Installation must be met. Then
Clone this repository locally with git
Navigate to the cloned repository
Create a virtual environment
python -m venv .venv
Activate the virtual environment
On Microsoft Windows run: .venv\Scripts\activate.bat On Linux run: source venv/bin/activate
Install the dependencies for the development environment
pip install -r dev-requirements.txt
or
python -m pip install -r dev-requirements
Building the py-pal module
python setup.py develop
With this command, the C extensions are compiled using Cython. Also, it packages all necessary files together and installs them in the current virtual environment.
Note, any change to a cython file (.pyx) requires recompilation, i.e. the above command must be executed again.
Attention, if it is not possible to install Cython by this command, the cython files (.pyx) are not taken into account. This results in the circumstance that the corresponding C/C++ files are not generated and thus, the old C/C++ files get used to build the C extensions. Directly speaking, changes to the cython files will have no effect because they are not processed!
Run all regular tests from the command line
pytest tests
Run all Cython tests from the command line
pytest tests_cython
Run all regular and Cython tests together from the command line
pytest
Command line usage of the py-pal module
python -m py_pal <target-module/file>
or
py-pal <target-module/file>
There are multiple aliases to the same command: py-pal, py_pal and pypal
See the help message:
py-pal -h
Programmatic usage of the py-pal module
The profile decorator:
from py_pal.core import profile
@profile
def test():
pass
By using the profile decorator, it is possible to annotate Python functions such that only the annotated Python functions will be profiled. It acts similar to a whitelist filter.
Another possibility is to use the context manager protocol:
from py_pal.estimator import AllArgumentEstimator
from py_pal.tracer import Tracer
with Tracer() as t:
pass
estimator = AllArgumentEstimator(t)
res = estimator.export()
# Do something with the resulting DataFrame
print(res)
The most verbose way to use the py-pal API:
from py_pal.estimator import AllArgumentEstimator
from py_pal.tracer import Tracer
t = Tracer()
t.trace()
# Your function
pass
t.stop()
estimator = AllArgumentEstimator(t)
res = estimator.export()
# Do something with the resulting DataFrame
print(res)
All examples instantiate a tracer object that is responsible for collecting the data. After execution, the collected data is passed to the analysis module. Finally, an estimate of the asymptotic runtime of the functions contained in the code is obtained.
Modes
In the current version py-pal offers only the profiling mode. Although py_pal.datagen offers some functions for generating inputs, py-pal must be combined with appropriate test cases to realize a performance testing mode. An automatic detection and generation of appropriate test inputs does not exist at the moment.
Limitations
The profiling approach implemented by the py-pal modules does not distinguish between different threads executing a Python function. Actually it is a major problem to profile a Python script which makes use of threads. The bytecode counting strategy will increase all counters of Python functions on the current call stack no matter what threads is executing it. Thus, the data points will not be accurate to what really happened during the profiled execution of the script.
Licensing Notes
This work integrates some code from the big_O project. More specifically, most code in py_pal.complexity, py_pal.datagen and py_pal.estimator.Estimator.infer_complexity is adapted from bigO.
What’s New in Py-PAL 1.0.0
More thorough testing from different combinations of requirements and Python versions.
Bug fixes
What’s New in Py-PAL 0.2.1
Refactoring
The estimator module was refactored which introduces a slight change to the API. Classes inheriting from Estimator now only specify how to transform the collected data with respect to the arguments of the function.
Instead of ComplexityEstimator you should use the AllArgumentEstimator class. Additionally there is the SeparateArgumentEstimator which is experimental.
What’s New in Py-PAL 0.1.6
More accurate Data Collection
The Tracer is enhanced by measuring builtin function calls with AdvancedOpcodeMetric.
Opcodes resembling a function call .e.g FUNCTION_CALL are filtered for built in function calls. If the called function is found in the complexity mapping a synthetic Opcode weight gets assigned. A builtin function call is evaluated using its argument and a pre-defined runtime complexity e.g. O(n log n) for sort().
The feature is enabled by default
The calculation produces a performance overhead and can be disabled by providing a OpcodeMetric instance to the Tracer
The AdvancedOpcodeMetric instance assigned to the Tracer provides statistics about how many builtin function calls were observed and how many were found in the complexity map
Bugfixes
Cleaning data after normalization introduced wrong data points
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for py_pal-1.0.2-cp39-cp39-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c831b298116e48e69ab1ffed8e0ff06dc69678737d984ff5283afe6364693215 |
|
MD5 | b070e80c6411132cff9231dd398c10a0 |
|
BLAKE2b-256 | b4da8f5b14f7d280320f79ffd1033551c101f5561aeddba14e1491f0bb161777 |
Hashes for py_pal-1.0.2-cp39-cp39-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d85cb21fdf0783515cf55b438197c2768c457c4ea4c934fe41bc19c662a4d8ee |
|
MD5 | 2309fd5e4b7da000664d8d006271518e |
|
BLAKE2b-256 | 0107ed94bcfb9390bf17f728cf7e79f42781d42b20ecd3e5bfbdcb2e270f1a0a |
Hashes for py_pal-1.0.2-cp39-cp39-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 37fb4f9e5b2b5cda799bbc3a0e2586fb24ac53fc8718d5bba614c8b9471b6219 |
|
MD5 | 6a268f621714bb2a364cf991cf829068 |
|
BLAKE2b-256 | 1e2d9cc8c1d3e504c517ab37d9f1217126e2c1a306f5b62aba454565e4283dfd |
Hashes for py_pal-1.0.2-cp38-cp38-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | dd6f121e6451c67291599cf786fcda33097e8a215e91542f5a40eaecab881ecc |
|
MD5 | 0145ac104bd5ef80242709756b81179a |
|
BLAKE2b-256 | 1a7a18639b3a3dd5fcb5887f9fecd71b53d264146cf211f40c910cbc44a5e3c4 |
Hashes for py_pal-1.0.2-cp38-cp38-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b160503667eb6e2148dd7f82f45429464c43ed251dc1db8a1e4e5d9e0fac68b3 |
|
MD5 | 1f51b77d8d0a08b47027214f82199d1a |
|
BLAKE2b-256 | 0e48e1054c2aabe1c5c83a6317c778593694a9db3e1fc23cbf3a4eeffeff6f73 |
Hashes for py_pal-1.0.2-cp38-cp38-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6839d25a6a776c05ed0b701fae264eea0f0e08066a66b8c48b9eeab9be1be6b1 |
|
MD5 | 83f88ee05c1f1c9b5d005279bc6093ec |
|
BLAKE2b-256 | 50a318a2eac4091fd112d4984cc4230d2b187b4d36e8295fd512838852f6b65f |
Hashes for py_pal-1.0.2-cp37-cp37m-manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 183159c6c60e4cab61b267d63a9276bc141c154c4d5788236016079618e10200 |
|
MD5 | a63535b1b3ad10782028b64a8f8b408c |
|
BLAKE2b-256 | 0d212a45006d34046cde09c9611b8bd1551cd393ccea6e498d23906802ffe542 |
Hashes for py_pal-1.0.2-cp37-cp37m-manylinux2010_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 324699e0387e44b33f022be3412c5c7a042597981ad7cfae710e3a17460dd184 |
|
MD5 | 732d01673250da3f0cb13b13345d8fb4 |
|
BLAKE2b-256 | 2300175c85d2eb25e157e554010453636bc7900df3a914882bff682f2882fab4 |
Hashes for py_pal-1.0.2-cp37-cp37m-manylinux1_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b74acfeed248fa4e5b3ff819319cfcfb3b9dd19204bd25e2d77d78133c51ff1f |
|
MD5 | ac0c1c3bbcd069e067b9636a97c92b94 |
|
BLAKE2b-256 | f26cc007dc39435312d30bfceacf0f9e8f052f4c754d4d024d544ea6a2d461c6 |