Contribute to source code, documentation, examples and report issues: https://github.com/hardbyte/python-can
There is also a python-can mailing list for development discussion.
Building & Installing¶
The following assumes that the commands are executed from the root of the repository:
- The project can be built and installed with
python setup.py buildand
python setup.py install.
- The unit tests can be run with
python setup.py test. The tests can be run with
pypy3to test with other python versions, if they are installed. Maybe, you need to execute
pip3 install python-can[test](or only
pipfor Python 2), if some dependencies are missing.
- The docs can be built with
sphinx-build doc/ doc/_build. Appending
-nto the command makes Sphinx complain about more subtle problems.
Creating a new interface/backend¶
These steps are a guideline on how to add a new backend to python-can.
- Create a module (either a
*.pyor an entire subdirctory depending on the complexity) inside
- Implement the central part of the backend: the bus class that extends
can.BusABC. See below for more info on this one!
- Register your backend bus class in
- Add docs where appropiate, like in
doc/interfaces.rstand add an entry in
- Add tests in
- Concrete implementations have to implement the following:
- They might implement the following:
flush_tx_buffer()to allow discrading any messages yet to be sent
shutdown()to override how the bus should shut down
send_periodic()to override the software based periodic sending and push it down to the kernel or hardware
_apply_filters()to apply efficient filters to lower level systems like the OS kernel or hardware
_detect_available_configs()to allow the interface to report which configurations are currently available for new connections
state()property to allow reading and/or changing the bus state
TL;DR: Only override
Previously, concrete bus classes had to override
directly instead of
_recv_internal(), but that has
changed to allow the abstract base class to handle in-software message
filtering as a fallback. All internal interfaces now implement that new
behaviour. Older (custom) interfaces might still be implemented like that
and thus might not provide message filtering:
The modules in
|interfaces||Contains interface dependent code.|
|bus||Contains the interface independent Bus object.|
|message||Contains the interface independent Message object.|
|io||Contains a range of file readers and writers.|
|broadcastmanager||Contains interface independent broadcast manager code.|
|CAN||Legacy API. Deprecated.|
Creating a new Release¶
- Release from the
- Update the library version in
__init__.pyusing semantic versioning.
- Run all tests and examples against available hardware.
- Update CONTRIBUTORS.txt with any new contributors.
- For larger changes update
- Sanity check that documentation has stayed inline with code.
- Create a temporary virtual environment. Run
python setup.py installand
python setup.py test
- Create and upload the distribution:
python setup.py sdist bdist_wheel
- Sign the packages with gpg
gpg --detach-sign -a dist/python_can-X.Y.Z-py3-none-any.whl
- Upload with twine
twine upload dist/python-can-X.Y.Z*
- In a new virtual env check that the package can be installed with pip:
pip install python-can==X.Y.Z
- Create a new tag in the repository.
- Check the release on PyPi, Read the Docs and GitHub.