diff --git a/AUTHORS.txt b/AUTHORS.txt deleted file mode 100644 index bf30c4a..0000000 --- a/AUTHORS.txt +++ /dev/null @@ -1,5 +0,0 @@ -Gabriel Pettier -Andre Miras -Armin Sebastian -Ray Chang -Tamas Levai diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..29d18fa --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,8 @@ +In the interest of fostering an open and welcoming community, we as +contributors and maintainers need to ensure participation in our project and +our sister projects is a harassment-free and positive experience for everyone. +It is vital that all interaction is conducted in a manner conveying respect, +open-mindedness and gratitude. + +Please consult the [latest Kivy Code of Conduct](https://github.com/kivy/kivy/blob/master/CODE_OF_CONDUCT.md). + diff --git a/CONTACT.md b/CONTACT.md new file mode 100644 index 0000000..7478622 --- /dev/null +++ b/CONTACT.md @@ -0,0 +1,6 @@ +# Contacting the Kivy Team + +If you are looking to contact the Kivy Team (who are responsible for managing +the OSCPy project), including looking for support, please see our +latest [Contact Us](https://github.com/kivy/kivy/blob/master/CONTACT.md) +document. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fd2d7e4..55a5bee 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,51 +1,47 @@ -### CONTRIBUTING +# Contribution Guidelines -This software is open source and welcomes open contributions, there are just -a few guidelines, if you are unsure about them, please ask and guidance will be -provided. +OSCPy is part of the [Kivy](https://kivy.org) ecosystem - a large group of +products used by many thousands of developers for free, but it +is built entirely by the contributions of volunteers. We welcome (and rely on) +users who want to give back to the community by contributing to the project. -- The code is [hosted on GitHub](https://github.com/kivy/oscpy) and - development happens here, using the tools provided by the platform. - Contributions are accepted in the form of Pull Requests. Bugs are to be - reported in the issue tracker provided there. +Contributions can come in many forms. See the latest +[Contribution Guidelines](https://github.com/kivy/kivy/blob/master/CONTRIBUTING.md) +for how you can help us. -- Please follow [PEP8](https://www.python.org/dev/peps/pep-0008/), hopefully - your editor can be configured to automatically enforce it, but you can also - install (using pip) and run `pycodestyle` from the command line, - to get a report about it. +.. warning:: + The OSCPy process differs in small but important ways from the + Kivy framework's process. See below. -- Avoid lowering the test coverage, it's hard to achieve 100%, but staying as +# oscpy Contribution Hints + +- Avoid lowering the test coverage. It's hard to achieve 100%, but staying as close to it as possible is a good way to improve quality by catching bugs as - early as possible. Tests are ran by Travis, and the coverage is + early as possible. + + Tests are automatically run in GitHub on a Pull Request, and the coverage is evaluated by Coveralls, so you'll get a report about your contribution - breaking any test, and the evolution of coverage, but you can also check that - locally before sending the contribution, by using `pytest --cov-report - term-missing --cov oscpy`, you can also use `pytest --cov-report html --cov - oscpy` to get an html report that you can open in your browser. + breaking any test, and the evolution of coverage. You can also check that + locally before sending the contribution, by using: -- Please try to conform to the style of the codebase, if you have a question, - just ask. + pytest --cov-report term-missing --cov oscpy -- Please keep performance in mind when editing the code, if you - see room for improvement, share your suggestions by opening an issue, - or open a pull request directly. + To get get an html report that you can open in your browser: -- Please keep in mind that the code you contribute will be subject to the MIT - license, don't include code if it's not under a compatible license, and you - are not the copyright holder. + pytest --cov-report html --cov oscpy -#### Tips +- Please keep performance in mind when editing the code. -You can install the package in `editable` mode, with the `dev` option, -to easily have all the required tools to check your edits. +- You can install the package in `editable` mode, with the `dev` option, + to easily have all the required tools to check your edits. - pip install --editable .[dev] + pip install --editable .[dev] -You can make sure the tests are ran before pushing by using the git hook. +- You can make sure the tests are run before pushing by using the git hook. - cp tools/hooks/pre-commit .git/hooks/ + cp tools/hooks/pre-commit .git/hooks/ -If you are unsure of the meaning of the pycodestyle output, you can use the ---show-pep8 flag to learn more about the errors. +- If you are unsure of the meaning of the pycodestyle output, you can use the + `--show-pep8` flag to learn more about the errors. - pycodestyle --show-pep8 + pycodestyle --show-pep8 diff --git a/LICENSE.txt b/LICENSE similarity index 93% rename from LICENSE.txt rename to LICENSE index 57278fb..f8bab5b 100644 --- a/LICENSE.txt +++ b/LICENSE @@ -1,4 +1,6 @@ -Copyright (c) 2018 Gabriel Pettier & al +MIT License + +Copyright (c) 2018-2023 Kivy Team and other contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal diff --git a/README.md b/README.md index 62e9278..4f9f493 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,50 @@ ### OSCPy -[![Coverage Status](https://coveralls.io/repos/github/kivy/oscpy/badge.svg?branch=master)](https://coveralls.io/github/kivy/oscpy?branch=master) -CI is done by Github Checks, see the current commit for build status. +OSCPy is a Python implementation of Open Sound Control (OSC) network protocol. + +OSCPy is managed by the [Kivy Team](https://kivy.org/about.html). + +[![Backers on Open Collective](https://opencollective.com/kivy/backers/badge.svg)](https://opencollective.com/kivy) +[![Sponsors on Open Collective](https://opencollective.com/kivy/sponsors/badge.svg)](https://opencollective.com/kivy) +[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md) +![PyPI - Version](https://img.shields.io/pypi/v/oscpy) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/oscpy) -A modern implementation of OSC for python2/3. +[![PR Tests](https://github.com/kivy/oscpy/actions/workflows/push.yml/badge.svg)](https://github.com/kivy/oscpy/actions/workflows/push.yml) +[![Coverage Status](https://coveralls.io/repos/github/kivy/oscpy/badge.svg?branch=master)](https://coveralls.io/github/kivy/oscpy?branch=master) + +#### What is OSC? -#### What is OSC. +[Open Sound Control](http://opensoundcontrol.org/) (OSC) is a +[UDP](https://en.wikipedia.org/wiki/User_Datagram_Protocol)-based network +protocol that was designed for fast dispatching of time-sensitive messages. -OpenSoundControl is an UDP based network protocol, that is designed for fast -dispatching of time-sensitive messages, as the name suggests, it was designed -as a replacement for MIDI, but applies well to other situations. The protocol is -simple to use, OSC addresses look like http URLs, and accept various basic -types, such as string, float, int, etc. You can think of it basically as an -http POST, with less overhead. +As the name suggests, it was designed as a replacement for +[MIDI](https://en.wikipedia.org/wiki/MIDI), but applies well to other +situations. The protocol is simple to use. OSC addresses look like HTTP URLs. +It accepts various basic types, such as string, float and int. -You can learn more about OSC on [OpenSoundControl.org](http://opensoundcontrol.org/) +You can think of it basically as an +[HTTP POST](https://en.wikipedia.org/wiki/POST_(HTTP)), with less overhead. -#### Goals +#### OSCPy Design Goals -- python2.7/3.6+ compatibility (can be relaxed more on the python3 side - if needed, but nothing before 2.7 will be supported) +- modern, pure Python implementation - fast -- easy to use +- easy-to-use - robust (returns meaningful errors in case of malformed messages, always do the right thing on correct messages, and by default intercept+log the exceptions raised by callbacks) - separation of concerns (message parsing vs communication) -- sync and async compatibility (threads, asyncio, trio…) -- clean and easy to read code +- sync and async compatibility (threads, `asyncio`, `trio`) +- clean and easy-to-read code #### Features - serialize and parse OSC data types/Messages/Bundles -- a thread based udp server to open sockets (INET or UNIX) and bind callbacks on osc addresses on them +- a thread-based UDP server to open sockets (INET or UNIX) +- bind callbacks on OSC addresses - a simple client #### Install @@ -152,10 +163,9 @@ for i in range(10): #### Unicode By default, the server and client take bytes (encoded strings), not unicode -strings, for osc addresses as well as osc strings. However, you can pass an +strings, for OSC addresses as well as OSC strings. However, you can pass an `encoding` parameter to have your strings automatically encoded and decoded by -them, so your callbacks will get unicode strings (unicode in python2, str in -python3). +them, so your callbacks will get unicode strings. ```python osc = OSCThreadServer(encoding='utf8') @@ -179,7 +189,7 @@ send_message( #### CLI -OSCPy provides an "oscli" util, to help with debugging: +OSCPy provides an "oscli" utility to help with debugging: - `oscli dump` to listen for messages and dump them - `oscli send` to send messages or bundles to a server @@ -188,7 +198,7 @@ See `oscli -h` for more information. #### GOTCHAS - `None` values are not allowed in serialization -- Unix-type sockets must not already exist when you listen() on them +- Unix-type sockets must not already exist when you `listen()` on them #### TODO @@ -198,11 +208,75 @@ See `oscli -h` for more information. - an asyncio-oriented server implementation - examples & documentation -#### Contributing +## License + +OSCPy is [MIT licensed](LICENSE), actively developed by a great +community and is supported by many projects managed by the +[Kivy Organization](https://www.kivy.org/about.html). + +## Support + +Are you having trouble using OSCPy or any of its related projects +in the Kivy ecosystem? +Is there an error you don’t understand? Are you trying to figure out how to use +it? We have volunteers who can help! + +The best channels to contact us for support are listed in the latest +[Contact Us](https://github.com/kivy/oscpy/blob/master/CONTACT.md) +document. + +## Code of Conduct + +In the interest of fostering an open and welcoming community, we as +contributors and maintainers need to ensure participation in our project and +our sister projects is a harassment-free and positive experience for everyone. +It is vital that all interaction is conducted in a manner conveying respect, +open-mindedness and gratitude. + +Please consult the [latest Code of Conduct](https://github.com/kivy/oscpy/blob/master/CODE_OF_CONDUCT.md). + +## Contributors + +This project exists thanks to +[all the people who contribute](https://github.com/kivy/oscpy/graphs/contributors). +[[Become a contributor](CONTRIBUTING.md)]. + + + +## Backers + +Thank you to [all of our backers](https://opencollective.com/kivy)! +🙏 [[Become a backer](https://opencollective.com/kivy#backer)] + + + +## Sponsors + +Special thanks to +[all of our sponsors, past and present](https://opencollective.com/kivy). +Support this project by +[[becoming a sponsor](https://opencollective.com/kivy#sponsor)]. + +Here are our top current sponsors. Please click through to see their websites, +and support them as they support us. + + + + + + -Check out our [contribution guide](CONTRIBUTING.md) and feel free to improve OSCPy. + + + + -#### License + + + + -OSCPy is released under the terms of the MIT License. -Please see the [LICENSE.txt](LICENSE.txt) file. + + + + diff --git a/setup.py b/setup.py index 244fa54..305a5c2 100644 --- a/setup.py +++ b/setup.py @@ -18,7 +18,9 @@ name='oscpy', # https://packaging.python.org/en/latest/single_source_version.html version=__version__, - description='A modern and efficient OSC Client/Server implementation', + description=( + 'A Python implementation of Open Sound Control (OSC) network protocol' + ), long_description=long_description, long_description_content_type='text/markdown', url=URL, @@ -31,20 +33,19 @@ 'Topic :: Software Development :: Libraries', 'Topic :: System :: Networking', 'License :: OSI Approved :: MIT License', - 'Programming Language :: Python :: 2', - 'Programming Language :: Python :: 2.7', 'Programming Language :: Python :: 3', - 'Programming Language :: Python :: 3.4', - 'Programming Language :: Python :: 3.5', - 'Programming Language :: Python :: 3.6', - 'Programming Language :: Python :: 3.7', + 'Programming Language :: Python :: 3.8', + 'Programming Language :: Python :: 3.9', + 'Programming Language :: Python :: 3.10', + 'Programming Language :: Python :: 3.11', + 'Programming Language :: Python :: 3.12', ], keywords='OSC network udp', packages=find_packages(exclude=['contrib', 'docs', 'tests']), install_requires=[], extras_require={ - 'dev': ['pytest>=3.6', 'wheel', 'pytest-cov', 'pycodestyle'], + 'dev': ['pytest>=3.8', 'wheel', 'pytest-cov', 'pycodestyle'], 'ci': ['coveralls', 'pytest-rerunfailures'], }, package_data={},