Developer’s Overview¶
Contributing¶
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.
Some more information about the internals of this library can be found
in the chapter Internal API.
There is also additional information on extending the can.io
module.
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 build
andpython setup.py install
. - The unit tests can be run with
python setup.py test
. The tests can be run withpython2
,python3
,pypy
orpypy3
to test with other python versions, if they are installed. Maybe, you need to executepip3 install python-can[test]
(or onlypip
for Python 2), if some dependencies are missing. - The docs can be built with
sphinx-build doc/ doc/_build
. Appending-n
to 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
*.py
or an entire subdirectory depending on the complexity) insidecan.interfaces
- Implement the central part of the backend: the bus class that extends
can.BusABC
. See Extending the BusABC class for more info on this one! - Register your backend bus class in
can.interface.BACKENDS
andcan.interfaces.VALID_INTERFACES
incan.interfaces.__init__.py
. - Add docs where appropriate. At a minimum add to
doc/interfaces.rst
and add a new interface specific document indoc/interface/*
. - Update
doc/scripts.rst
accordingly. - Add tests in
test/*
where appropriate.
Code Structure¶
The modules in python-can
are:
Module | Description |
---|---|
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. |
Process for creating a new Release¶
Note many of these steps are carried out by the CI system on creating a tag in git.
- Release from the
master
branch. - Update the library version in
__init__.py
using semantic versioning. - Check if any deprecations are pending.
- Run all tests and examples against available hardware.
- Update CONTRIBUTORS.txt with any new contributors.
- For larger changes update
doc/history.rst
. - Sanity check that documentation has stayed inline with code.
- Create a temporary virtual environment. Run
python setup.py install
andpython setup.py test
. - Ensure the
setuptools
andwheel
tools are up to date:pip install -U setuptools wheel
. - Create and upload the distribution:
python setup.py sdist bdist_wheel
. - [Optionally] 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.