diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 74b2533..04162d9 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -21,6 +21,7 @@ jobs: - ["3.9", "py39"] - ["3.10", "py310"] - ["pypy3", "pypy3"] + - ["3.10", "docs"] runs-on: ubuntu-latest name: ${{ matrix.config[1] }} diff --git a/CHANGES.rst b/CHANGES.rst index 00ad517..21513ae 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -5,7 +5,11 @@ Changelog 5.0.0a2 (unreleased) -------------------- -- Nothing changed yet. +Bug fixes: + +- Changed tools.UIDGenerator instance methods to static methods + Ref: #345 + [spralja] 5.0.0a1 (2022-07-11) @@ -17,7 +21,9 @@ Breaking changes: New features: -- *add item here* +- Document development setup + Ref: #358 + [niccokunzmann] Bug fixes: diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 66e28eb..37e0bc6 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -21,3 +21,11 @@ For pull requests, keep this in mind - Describe your change in CHANGES.rst - Add yourself to the docs/credits.rst + +Development Setup +----------------- + +If you would like to setup icalendar to +contribute changes, the `Installation Section +`_ +should help you further. diff --git a/README.rst b/README.rst index 8290f41..901d477 100644 --- a/README.rst +++ b/README.rst @@ -16,10 +16,6 @@ files. ---- - -.. image:: https://travis-ci.org/collective/icalendar.svg?branch=master - :target: https://travis-ci.org/collective/icalendar - .. image:: https://badge.fury.io/py/icalendar.svg :target: https://pypi.org/project/icalendar/ :alt: Python Package Version on PyPI @@ -28,6 +24,14 @@ files. :target: https://pypi.org/project/icalendar/#files :alt: Downloads from PyPI +.. image:: https://github.com/collective/icalendar/actions/workflows/tests.yml/badge.svg + :target: https://github.com/collective/icalendar/actions/workflows/tests.yml + :alt: GitHub Actions build status for master + +.. image:: https://github.com/collective/icalendar/actions/workflows/tests.yml/badge.svg?branch=4.x + :target: https://github.com/collective/icalendar/actions/workflows/tests.yml + :alt: GitHub Actions build status for 4.x + .. _`icalendar`: https://pypi.org/project/icalendar/ .. _`RFC 5545`: https://www.ietf.org/rfc/rfc5545.txt .. _`python-dateutil`: https://github.com/dateutil/dateutil/ diff --git a/docs/credits.rst b/docs/credits.rst index 420af8d..bf146f3 100644 --- a/docs/credits.rst +++ b/docs/credits.rst @@ -56,6 +56,9 @@ icalendar contributors - Clive Stevens - Dalton Durst - Kamil Mańkowski +- `Nicco Kunzmann `_ +- Robert Spralja +- Maurits van Rees Find out who contributed:: diff --git a/docs/install.rst b/docs/install.rst index 8556b05..0c573d3 100644 --- a/docs/install.rst +++ b/docs/install.rst @@ -10,6 +10,109 @@ package, like this:: >>> import icalendar +Development Setup +----------------- + +To start contributing changes to icalendar, +you can clone the project to your file system +using Git. +You can `fork `_ +the project first and clone your fork, too. + +.. code-block:: bash + + git clone https://github.com/collective/icalendar.git + cd icalendar + +Installing Python +----------------- + +You will need a version of Python installed to run the tests +and execute the code. +The latest version of Python 3 should work and will be enough +to get you started. +If you like to run the tests with different Python versions, +the following setup proecess should work the same. + +Install Tox +----------- + +First, install `tox `_.. + +.. code-block:: bash + + pip install tox + +From now on, tox will manage Python versions and +test commands for you. + +Running Tests +------------- + +``tox`` manages all test environments in all Python versions. + +To run all tests in all environments, simply run ``tox`` + +.. code-block:: bash + + tox + +You may not have all Python versions installed or +you may want to run a specific one. +Have a look at the `documentation +`__. +This is how you can run ``tox`` with Python 3.9: + +.. code-block:: bash + + tox -e py39 + +Accessing a ``tox`` environment +------------------------------- + +If you like to enter a specific tox environment, +you can do this: + +.. code-block:: bash + + source .tox/py39/bin/activate + +Install ``icalendar`` Manually +------------------------------- + +The best way to test the package is to use ``tox`` as +described above. +If for some reason you cannot install ``tox``, you can +go ahead with the following section using your +installed version of Python and ``pip``. + +If for example, you would like to use your local copy of +icalendar in another Python environment, +this section explains how to do it. + +You can install the local copy of ``icalendar`` with ``pip`` +like this: + +.. code-block:: bash + + cd icalendar + python -m pip install -e . + +This installs the module and dependencies in your +Python environment so that you can access local changes. +If tox fails to install ``icalendar`` during its first run, +you can activate the environment in the ``.tox`` folder and +manually setup ``icalendar`` like this. + +Try it out: + +.. code-block:: python + + Python 3.9.5 (default, Nov 23 2021, 15:27:38) + Type "help", "copyright", "credits" or "license" for more information. + >>> import icalendar + >>> icalendar.__version__ + '4.0.10.dev0' Building the documentation locally ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -18,10 +121,7 @@ To build the documentation follow these steps: .. code-block:: bash - $ git clone https://github.com/collective/icalendar.git - $ cd icalendar - $ virtualenv-2.7 . - $ source bin/activate + $ source .tox/py39/bin/activate $ pip install -r requirements_docs.txt $ cd docs $ make html @@ -29,3 +129,10 @@ To build the documentation follow these steps: You can now open the output from ``_build/html/index.html``. To build the presentation-version use ``make presentation`` instead of ``make html``. You can open the presentation at ``presentation/index.html``. + +You can also use ``tox`` to build the documentation: + +.. code-block:: bash + + cd icalendar + tox -e docs diff --git a/src/icalendar/tests/test_fixed_issues.py b/src/icalendar/tests/test_fixed_issues.py index 772a7d5..7f5aa86 100644 --- a/src/icalendar/tests/test_fixed_issues.py +++ b/src/icalendar/tests/test_fixed_issues.py @@ -478,3 +478,16 @@ END:VCALENDAR""" expected_tzname = 'Brasília standard'.encode('ascii', 'replace') self.assertEqual(dtstart.tzinfo.zone, expected_zone) self.assertEqual(dtstart.tzname(), expected_tzname) + + def test_issue_345(self): + """Issue #345 - Why is tools.UIDGenerator a class (that must be instantiated) instead of a module? """ + uid1 = icalendar.tools.UIDGenerator.uid() + uid2 = icalendar.tools.UIDGenerator.uid('test.test') + uid3 = icalendar.tools.UIDGenerator.uid(unique='123') + uid4 = icalendar.tools.UIDGenerator.uid('test.test', '123') + + self.assertEqual(uid1.split('@')[1], 'example.com') + self.assertEqual(uid2.split('@')[1], 'test.test') + self.assertEqual(uid3.split('-')[1], '123@example.com') + self.assertEqual(uid4.split('-')[1], '123@test.test') + diff --git a/src/icalendar/tools.py b/src/icalendar/tools.py index 4d3ba3a..9209095 100644 --- a/src/icalendar/tools.py +++ b/src/icalendar/tools.py @@ -15,19 +15,21 @@ class UIDGenerator(object): """ chars = list(ascii_letters + digits) - def rnd_string(self, length=16): + @staticmethod + def rnd_string(length=16): """Generates a string with random characters of length. """ - return ''.join([random.choice(self.chars) for _ in range(length)]) + return ''.join([random.choice(UIDGenerator.chars) for _ in range(length)]) - def uid(self, host_name='example.com', unique=''): + @staticmethod + def uid(host_name='example.com', unique=''): """Generates a unique id consisting of: datetime-uniquevalue@host. Like: 20050105T225746Z-HKtJMqUgdO0jDUwm@example.com """ host_name = to_unicode(host_name) - unique = unique or self.rnd_string() + unique = unique or UIDGenerator.rnd_string() today = to_unicode(vDatetime(datetime.today()).to_ical()) return vText('%s-%s@%s' % (today, unique, diff --git a/tox.ini b/tox.ini index 5ca2293..674c864 100644 --- a/tox.ini +++ b/tox.ini @@ -1,16 +1,23 @@ # to run for a specific environment, use ``tox -e ENVNAME`` [tox] -envlist = py27,py36,py37,py38,py39,py310,pypy3 +envlist = py27,py37,py38,py39,py310,pypy3,docs [testenv] +usedevelop=True deps = pytest coverage - py{27,36}: hypothesis>=3.0 -extras = - test + py{27}: hypothesis>=3.0 commands = coverage run --source=src/icalendar --omit=*/tests/* --module pytest [] - py{27,36}: coverage run --append --source=src/icalendar --omit=*/tests/* --module pytest [] src/icalendar/tests/hypothesis/ + py{27}: coverage run --append --source=src/icalendar --omit=*/tests/* --module pytest [] src/icalendar/tests/hypothesis/ coverage report coverage html + +[testenv:docs] +deps = + -r {toxinidir}/requirements_docs.txt +changedir = docs +allowlist_externals = make +commands = + make html