A Python module and program to convert calendars using X-WR-TIMEZONE to standard ones.
.. image:: https://img.shields.io/gitlab/pipeline-status/niccokunzmann/x-wr-timezone?branch=master :target: https://gitlab.com/niccokunzmann/x-wr-timezone/-/jobs :alt: Gitlab 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:
pip
.wget
or curl
.Some of the requirements are:
X-WR-TIMEZONE
are kept unchanged.Install using pip
:
.. code:: shell
python3 -m pip install x-wr-timezone
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>
_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
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..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.Clone the repository <https://github.com/niccokunzmann/x-wr-timezone>
_ or its fork and cd x-wr-timezone
.
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
Install the packages and this module so it can be edited:
.. code-block:: shell
pip install -r test-requirements.txt -e .
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
To release new versions,
edit the Changelog Section
edit setup.py, the __version__
variable
create a commit and push it
Wait for CI tests <https://gitlab.com/niccokunzmann/x-wr-timezone/-/jobs>
_ to finish the build.
run
.. code-block:: shell
python3 setup.py tag_and_deploy
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/master/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.
v0.0.6
v0.0.5
Pull Request 7 <https://github.com/niccokunzmann/x-wr-timezone/pull/7>
__v0.0.4
v0.0.3
tzname()
function of datetime
to test for UTC. This helps support zoneinfo time zones.v0.0.2
timezone
argument.calendar
argument and only copy it where needed.v0.0.1
x-wr-timezone
.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>
__This module uses the icalendar
library for parsing calendars.
This library is used by python-recurring-ical-events
to get events at specific dates.
This software is licensed under LGPLv3, see the LICENSE file.