Merge branch 'master' into patch-2

.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] }}

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:
 

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
+<https://icalendar.readthedocs.io/en/latest/install.html>`_
+should help you further.

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/

docs/credits.rst

@@ -56,6 +56,9 @@ icalendar contributors
 - Clive Stevens <clivest2@gmail.com>
 - Dalton Durst <github@daltondur.st>
 - Kamil Mańkowski <kam193@wp.pl>
+- `Nicco Kunzmann <https://github.com/niccokunzmann>`_
+- Robert Spralja <robert.spralja@gmail.com>
+- Maurits van Rees <maurits@vanrees.org>
 
 Find out who contributed::
 

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 <https://github.com/collective/icalendar/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 <https://pypi.org/project/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
+<https://tox.wiki/en/latest/example/general.html#selecting-one-or-more-environments-to-run-tests-against>`__.
+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

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')
+        

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,

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