X-WR-TIMEZONE
=============
.. image:: https://github.com/niccokunzmann/x-wr-timezone/actions/workflows/tests.yml/badge.svg
:target: https://github.com/niccokunzmann/x-wr-timezone/actions/workflows/tests.yml
:alt: CI build and test status
.. image:: https://badge.fury.io/py/x-wr-timezone.svg
:target: https://pypi.python.org/pypi/x-wr-timezone
:alt: Python Package Version on Pypi
.. image:: https://img.shields.io/pypi/dm/x-wr-timezone.svg
:target: https://pypi.python.org/pypi/x-wr-timezone#downloads
:alt: Downloads from Pypi
.. image:: https://img.shields.io/opencollective/all/open-web-calendar?label=support%20on%20open%20collective
:target: https://opencollective.com/open-web-calendar/
:alt: Support on Open Collective
Some calendar providers introduce the non-standard ``X-WR-TIMEZONE`` parameter
to ICS calendar files.
Strict interpretations according to RFC 5545 ignore the ``X-WR-TIMEZONE``
parameter.
This causes the times of the events to differ from those
which make use of ``X-WR-TIMEZONE``.
This module aims to bridge the gap by converting calendars
using ``X-WR-TIMEZONE`` to a strict RFC 5545 calendars.
So, let's put our heads together and solve this problem for everyone!
Some features of the module are:
- Easy install with Python's ``pip``.
- Command line conversion of calendars.
- Piping of calendar files with ``wget`` or ``curl``.
Some of the requirements are:
- Calendars without ``X-WR-TIMEZONE`` are kept unchanged.
- Passing calendars twice to this module does not change them.
Install
-------
Install using ``pip``:
.. code:: shell
python3 -m pip install x-wr-timezone
Install with ``apt``:
.. code:: shell
sudo apt-get install python-x-wr-timezone
Support
-------
- `Donate using GitHub Sponsors <https://github.com/sponsors/niccokunzmann>`_
- `Donate using Open Collective <https://opencollective.com/open-web-calendar/>`_
- `Donate using thanks.dev <https://thanks.dev>`_
Command Line Usage
------------------
You can standardize the calendars using your command line interface.
The examples assume that ``in.ics`` is a calendar which may use
``X-WR-TIMEZONE``, whereas ``out.ics`` does not require ``X-WR-TIMEZONE``
for proper display.
.. code-block:: shell
cat in.is | x-wr-timezone > out.ics
x-wr-timezone in.ics out.ics
curl https://example.org/in.ics | x-wr-timezone > out.ics
wget -O- https://example.org/in.ics | x-wr-timezone > out.ics
You can get usage help on the command line:
.. code-block:: shell
x-wr-timezone --help
Python
------
After you have installed the library, you can import it.
.. code:: python
import x_wr_timezone
The function ``to_standard()`` converts an ``icalendar`` object.
.. code:: python
x_wr_timezone.to_standard(an_icalendar)
Here is a full example which does about as much as this module is supposed to do:
.. code-block:: python
import icalendar # installed with x_wr_timezone
import x_wr_timezone
with open("in.ics", 'rb') as file:
calendar = icalendar.from_ical(file.read())
new_calendar = x_wr_timezone.to_standard(calendar)
# you could use the new_calendar variable now
with open('out.ics', 'wb') as file:
file.write(new_calendar.to_ical())
``to_standard(calendar, timezone=None)`` has these parameters:
- ``calendar`` is the ``icalendar.Calendar`` object.
- ``timezone`` is an optional time zone. By default, the time zone in
``calendar['X-WR-TIMEZONE']`` is used to check if the calendar needs
changing.
When ``timezone`` is not ``None`` however, ``calendar['X-WR-TIMEZONE']``
will not be tested and it is assumed that the ``calendar`` should be
changed as if ``calendar['X-WR-TIMEZONE']`` had the value of ``timezone``.
This does not add or change the value of ``calendar['X-WR-TIMEZONE']``.
You would need to do that yourself.
``timezone`` can be a string like ``"UTC"`` or ``"Europe/Berlin"`` or
a ``pytz.timezone`` or something that ``datetime`` accepts as a time zone..
- Return value: The ``calendar`` argument is not modified at all. The calendar
returned has the attributes and subcomponents of the ``calendar`` only
changed and copied where needed to return the proper value. As such,
the returned calendar might be identical to the one passed to the
function as the ``calendar`` argument. Keep that in mind if you modify the
return value.
Development
-----------
1. Clone the `repository <https://github.com/niccokunzmann/x-wr-timezone>`_ or its fork and ``cd x-wr-timezone``.
2. Optional: Install virtualenv and Python3 and create a virtual environment:
.. code-block:: shell
pip install virtualenv
virtualenv -p python3 ENV
source ENV/bin/activate # you need to do this for each shell
3. Install the packages and this module so it can be edited:
.. code-block:: shell
pip install -r test-requirements.txt -e .
4. Run the tests:
.. code-block:: shell
pytest
To test all functions:
.. code-block:: shell
pytest --x-wr-timezone all
Testing with ``tox``
********************
You can use ``tox`` to test the package in different Python versions.
.. code-block:: shell
tox
This tests all the different functionalities:
.. code-block:: shell
tox -- --x-wr-timezone all
New Releases
------------
To release new versions,
1. edit the Changelog Section
2. edit setup.py, the ``__version__`` variable
3. create a commit and push it
4. Wait for `CI tests <https://github.com/niccokunzmann/x-wr-timezone/actions/workflows/tests.yml>`_ to finish the build.
5. run
.. code-block:: shell
python3 setup.py tag_and_deploy
6. notify the issues about their release
Testing
*******
This project's development is driven by tests.
Tests assure a consistent interface and less knowledge lost over time.
If you like to change the code, tests help that nothing breaks in the future.
They are required in that sense.
Example code and ics files can be transferred into tests and speed up fixing bugs.
You can view the tests in the `test folder
<https://github.com/niccokunzmann/x-wr-timezones/tree/main/test>`_.
If you have a calendar ICS file for which this library does not
generate the desired output, you can add it to the ``test/calendars``
folder and write tests for what you expect.
If you like, `open an issue <https://github.com/niccokunzmann/x-wr-timezone/issues>`_ first, e.g. to discuss the changes and
how to go about it.
Changelog
---------
- v1.0.0
- Use `zoneinfo` instead of `pytz`
- Test compatibility with `pytz` and `zoneinfo` as argument to `to_standard`
- Remove `pytz` as a dependency
- Add `tzdata` as a dependency
- Add typing
- Update Python versions
- v0.0.7
- Rename master branch to main
- Use proper SPDX license ID
- Test Python 3.12
- v0.0.6
- Obsolete Python 3.7
- Support Python 3.11
- Fix localization issue for pytz when datetime has no timezone
- Run tests on GitHub Actions
- Require icalendar 5.0.11 for tests
- Fix pytz localization issue when dateime is not in UTC and has no time zone.
- v0.0.5
- Revisit README and CLI and fix spelling mistakes.
- Modified behavior to treat events without time zone found in a calendar using the X-WR-TIMEZONE property, see `Pull Request 7 <https://github.com/niccokunzmann/x-wr-timezone/pull/7>`__
- v0.0.4
- Test automatic deployment with Gitlab CI.
- v0.0.3
- Use ``tzname()`` function of ``datetime`` to test for UTC. This helps support zoneinfo time zones.
- Split up visitor class and rename it to walker.
- v0.0.2
- Implement the ``timezone`` argument.
- Do not modify the value of the ``calendar`` argument and only copy it where needed.
- v0.0.1
- Initial release supports DTSTART, DTEND, EXDATE, RDATE, RECURRENCE-ID attributes of events.
- Command line interface as ``x-wr-timezone``.
Related Work
------------
This module was reated beause of these issues:
- `icalendar#343 <https://github.com/collective/icalendar/issues/343>`__
- `python-recurring-ical-events#71 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/71>`__
Related Software
----------------
This module uses the ``icalendar`` library for parsing calendars.
This library is used by ``python-recurring-ical-events``
to get events at specific dates.
License
-------
This software is licensed under LGPLv3, see the LICENSE file.
Raw data
{
"_id": null,
"home_page": "https://github.com/niccokunzmann/x-wr-timezone",
"name": "x-wr-timezone",
"maintainer": null,
"docs_url": null,
"requires_python": null,
"maintainer_email": null,
"keywords": "icalendar",
"author": "Nicco Kunzmann",
"author_email": "niccokunzmann@rambler.ru",
"download_url": "https://files.pythonhosted.org/packages/ad/25/7f3972d5e4861203eadb0fa4ab285dce404005bea547a0685cb2427e711a/x_wr_timezone-1.0.1.tar.gz",
"platform": null,
"description": "X-WR-TIMEZONE\n=============\n\n.. image:: https://github.com/niccokunzmann/x-wr-timezone/actions/workflows/tests.yml/badge.svg\n :target: https://github.com/niccokunzmann/x-wr-timezone/actions/workflows/tests.yml\n :alt: CI build and test status\n\n.. image:: https://badge.fury.io/py/x-wr-timezone.svg\n :target: https://pypi.python.org/pypi/x-wr-timezone\n :alt: Python Package Version on Pypi\n\n.. image:: https://img.shields.io/pypi/dm/x-wr-timezone.svg\n :target: https://pypi.python.org/pypi/x-wr-timezone#downloads\n :alt: Downloads from Pypi\n\n.. image:: https://img.shields.io/opencollective/all/open-web-calendar?label=support%20on%20open%20collective\n :target: https://opencollective.com/open-web-calendar/\n :alt: Support on Open Collective\n\n\nSome calendar providers introduce the non-standard ``X-WR-TIMEZONE`` parameter\nto ICS calendar files.\nStrict interpretations according to RFC 5545 ignore the ``X-WR-TIMEZONE``\nparameter.\nThis causes the times of the events to differ from those\nwhich make use of ``X-WR-TIMEZONE``.\n\nThis module aims to bridge the gap by converting calendars\nusing ``X-WR-TIMEZONE`` to a strict RFC 5545 calendars.\nSo, let's put our heads together and solve this problem for everyone!\n\nSome features of the module are:\n\n- Easy install with Python's ``pip``.\n- Command line conversion of calendars.\n- Piping of calendar files with ``wget`` or ``curl``.\n\nSome of the requirements are:\n\n- Calendars without ``X-WR-TIMEZONE`` are kept unchanged.\n- Passing calendars twice to this module does not change them.\n\nInstall\n-------\n\nInstall using ``pip``:\n\n.. code:: shell\n\n python3 -m pip install x-wr-timezone\n\nInstall with ``apt``:\n\n.. code:: shell\n\n sudo apt-get install python-x-wr-timezone\n\nSupport\n-------\n\n- `Donate using GitHub Sponsors <https://github.com/sponsors/niccokunzmann>`_\n- `Donate using Open Collective <https://opencollective.com/open-web-calendar/>`_\n- `Donate using thanks.dev <https://thanks.dev>`_\n\nCommand Line Usage\n------------------\n\nYou can standardize the calendars using your command line interface.\nThe examples assume that ``in.ics`` is a calendar which may use\n``X-WR-TIMEZONE``, whereas ``out.ics`` does not require ``X-WR-TIMEZONE``\nfor proper display.\n\n.. code-block:: shell\n\n cat in.is | x-wr-timezone > out.ics\n x-wr-timezone in.ics out.ics\n curl https://example.org/in.ics | x-wr-timezone > out.ics\n wget -O- https://example.org/in.ics | x-wr-timezone > out.ics\n\nYou can get usage help on the command line:\n\n.. code-block:: shell\n\n x-wr-timezone --help\n\nPython\n------\n\nAfter you have installed the library, you can import it.\n\n.. code:: python\n\n import x_wr_timezone\n\nThe function ``to_standard()`` converts an ``icalendar`` object.\n\n.. code:: python\n\n x_wr_timezone.to_standard(an_icalendar)\n\nHere is a full example which does about as much as this module is supposed to do:\n\n.. code-block:: python\n\n import icalendar # installed with x_wr_timezone\n import x_wr_timezone\n\n with open(\"in.ics\", 'rb') as file:\n calendar = icalendar.from_ical(file.read())\n new_calendar = x_wr_timezone.to_standard(calendar)\n # you could use the new_calendar variable now\n with open('out.ics', 'wb') as file:\n file.write(new_calendar.to_ical())\n\n\n``to_standard(calendar, timezone=None)`` has these parameters:\n\n- ``calendar`` is the ``icalendar.Calendar`` object.\n- ``timezone`` is an optional time zone. By default, the time zone in\n ``calendar['X-WR-TIMEZONE']`` is used to check if the calendar needs\n changing.\n When ``timezone`` is not ``None`` however, ``calendar['X-WR-TIMEZONE']``\n will not be tested and it is assumed that the ``calendar`` should be\n changed as if ``calendar['X-WR-TIMEZONE']`` had the value of ``timezone``.\n This does not add or change the value of ``calendar['X-WR-TIMEZONE']``.\n You would need to do that yourself.\n ``timezone`` can be a string like ``\"UTC\"`` or ``\"Europe/Berlin\"`` or\n a ``pytz.timezone`` or something that ``datetime`` accepts as a time zone..\n- Return value: The ``calendar`` argument is not modified at all. The calendar\n returned has the attributes and subcomponents of the ``calendar`` only\n changed and copied where needed to return the proper value. As such,\n the returned calendar might be identical to the one passed to the\n function as the ``calendar`` argument. Keep that in mind if you modify the\n return value.\n\n\nDevelopment\n-----------\n\n1. Clone the `repository <https://github.com/niccokunzmann/x-wr-timezone>`_ or its fork and ``cd x-wr-timezone``.\n2. Optional: Install virtualenv and Python3 and create a virtual environment:\n\n .. code-block:: shell\n\n pip install virtualenv\n virtualenv -p python3 ENV\n source ENV/bin/activate # you need to do this for each shell\n\n3. Install the packages and this module so it can be edited:\n\n .. code-block:: shell\n\n pip install -r test-requirements.txt -e .\n\n4. Run the tests:\n\n .. code-block:: shell\n\n pytest\n\nTo test all functions:\n\n .. code-block:: shell\n\n pytest --x-wr-timezone all\n\nTesting with ``tox``\n********************\n\nYou can use ``tox`` to test the package in different Python versions.\n\n.. code-block:: shell\n\n tox\n\nThis tests all the different functionalities:\n\n.. code-block:: shell\n\n tox -- --x-wr-timezone all\n\nNew Releases\n------------\n\nTo release new versions,\n\n1. edit the Changelog Section\n2. edit setup.py, the ``__version__`` variable\n3. create a commit and push it\n4. Wait for `CI tests <https://github.com/niccokunzmann/x-wr-timezone/actions/workflows/tests.yml>`_ to finish the build.\n5. run\n\n .. code-block:: shell\n\n python3 setup.py tag_and_deploy\n6. notify the issues about their release\n\nTesting\n*******\n\nThis project's development is driven by tests.\nTests assure a consistent interface and less knowledge lost over time.\nIf you like to change the code, tests help that nothing breaks in the future.\nThey are required in that sense.\nExample code and ics files can be transferred into tests and speed up fixing bugs.\n\nYou can view the tests in the `test folder\n<https://github.com/niccokunzmann/x-wr-timezones/tree/main/test>`_.\nIf you have a calendar ICS file for which this library does not\ngenerate the desired output, you can add it to the ``test/calendars``\nfolder and write tests for what you expect.\nIf you like, `open an issue <https://github.com/niccokunzmann/x-wr-timezone/issues>`_ first, e.g. to discuss the changes and\nhow to go about it.\n\nChangelog\n---------\n\n- v1.0.0\n\n - Use `zoneinfo` instead of `pytz`\n - Test compatibility with `pytz` and `zoneinfo` as argument to `to_standard`\n - Remove `pytz` as a dependency\n - Add `tzdata` as a dependency\n - Add typing\n - Update Python versions\n\n- v0.0.7\n\n - Rename master branch to main\n - Use proper SPDX license ID\n - Test Python 3.12\n\n- v0.0.6\n\n - Obsolete Python 3.7\n - Support Python 3.11\n - Fix localization issue for pytz when datetime has no timezone\n - Run tests on GitHub Actions\n - Require icalendar 5.0.11 for tests\n - Fix pytz localization issue when dateime is not in UTC and has no time zone.\n\n- v0.0.5\n\n - Revisit README and CLI and fix spelling mistakes.\n - Modified behavior to treat events without time zone found in a calendar using the X-WR-TIMEZONE property, see `Pull Request 7 <https://github.com/niccokunzmann/x-wr-timezone/pull/7>`__\n- v0.0.4\n\n - Test automatic deployment with Gitlab CI.\n- v0.0.3\n\n - Use ``tzname()`` function of ``datetime`` to test for UTC. This helps support zoneinfo time zones.\n - Split up visitor class and rename it to walker.\n- v0.0.2\n\n - Implement the ``timezone`` argument.\n - Do not modify the value of the ``calendar`` argument and only copy it where needed.\n- v0.0.1\n\n - Initial release supports DTSTART, DTEND, EXDATE, RDATE, RECURRENCE-ID attributes of events.\n - Command line interface as ``x-wr-timezone``.\n\nRelated Work\n------------\n\nThis module was reated beause of these issues:\n\n- `icalendar#343 <https://github.com/collective/icalendar/issues/343>`__\n- `python-recurring-ical-events#71 <https://github.com/niccokunzmann/python-recurring-ical-events/issues/71>`__\n\nRelated Software\n----------------\n\nThis module uses the ``icalendar`` library for parsing calendars.\nThis library is used by ``python-recurring-ical-events``\nto get events at specific dates.\n\nLicense\n-------\n\nThis software is licensed under LGPLv3, see the LICENSE file.\n\n\n",
"bugtrack_url": null,
"license": "LGPL-3.0-or-later",
"summary": "A Python module and program to convert calendars using X-WR-TIMEZONE to standard ones.",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/niccokunzmann/x-wr-timezone"
},
"split_keywords": [
"icalendar"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "92929f0ad7ef8499f8175ca7153f0fac07d22ff4a6c6ead7d764895f1f6bb2cd",
"md5": "baa181947390efa680899c304b0cc076",
"sha256": "25a981f570ce43a90b2b62e6dea6fe58ea404cc2ec7c6b3e40605a60eb8ad868"
},
"downloads": -1,
"filename": "x_wr_timezone-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "baa181947390efa680899c304b0cc076",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 10431,
"upload_time": "2024-09-30T03:26:08",
"upload_time_iso_8601": "2024-09-30T03:26:08.802116Z",
"url": "https://files.pythonhosted.org/packages/92/92/9f0ad7ef8499f8175ca7153f0fac07d22ff4a6c6ead7d764895f1f6bb2cd/x_wr_timezone-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ad257f3972d5e4861203eadb0fa4ab285dce404005bea547a0685cb2427e711a",
"md5": "8a9b63b9b1c091d9f4899bbea94a25da",
"sha256": "720fb58275c450f9563deaa1118c69ecdcad70874e9c0b4a23dcb2c10584af80"
},
"downloads": -1,
"filename": "x_wr_timezone-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "8a9b63b9b1c091d9f4899bbea94a25da",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 16619,
"upload_time": "2024-09-30T03:26:10",
"upload_time_iso_8601": "2024-09-30T03:26:10.180408Z",
"url": "https://files.pythonhosted.org/packages/ad/25/7f3972d5e4861203eadb0fa4ab285dce404005bea547a0685cb2427e711a/x_wr_timezone-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-30 03:26:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "niccokunzmann",
"github_project": "x-wr-timezone",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "icalendar",
"specs": []
},
{
"name": "tzdata",
"specs": []
}
],
"tox": true,
"lcname": "x-wr-timezone"
}
JSON
