Package library (#19)

* Add documentation: README and better test calendar.

* example/test_calendar: Add an example of YAML anchors for templates

- YAML provides & to label a node, and ways to refer to it.  This
  allows you to make one template event, and copy it many times
  changing only one property (such as the begin time.
- This adds an example of this into example/test_calendar.yaml

* Packaging using flit

* ics into requirements and update GH action with cache and flit

* Add release action

* Update readme with package info and dev workflow

* Add warning and 0.1rc1

* BSD licensing

* Update .gitignore

* Apply suggestions from code review

Co-authored-by: Stefan van der Walt <sjvdwalt@gmail.com>

* Better PyPi with token instead of personal password

* Remove unnecessary information

* Use plain pip to install dev env

Co-authored-by: Richard Darst <rkd@zgib.net>
Co-authored-by: Stefan van der Walt <sjvdwalt@gmail.com>

.github/workflows/release.yml

@@ -0,0 +1,31 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - '*.*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Setup Python 3.10
+        uses: actions/setup-python@v2
+        with:
+          python-version: '3.10'
+          architecture: 'x64'
+
+      - name: Install flit
+        run: pip install flit
+
+      - name: Build
+        run: flit build
+
+      - name: Publish to PyPI
+        env:
+          FLIT_USERNAME: __token__
+          FLIT_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: |
+          flit publish

.github/workflows/test.yaml → .github/workflows/test.yml

@@ -17,15 +17,23 @@ jobs:
       with:
         python-version: ${{ matrix.python-version }}
 
+    - uses: actions/cache@v2
+      with:
+        path: ~/.cache/pip
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt', '**/pyproject.toml') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
-        pip install flake8 pytest
-        pip install -r requirements.txt -r requirements.dev.txt
+        pip install -r requirements.txt
+        pip install flit
+        flit install
 
     - name: Lint
       run: pre-commit run --all-files --show-diff-on-failure --color always
 
     - name: Test
       run: |
-        PYTHONPATH=. pytest
+        pytest

.gitignore

@@ -1,2 +1,31 @@
 *~
 **/__pycache__
+### Python template
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+
+# Distribution / packaging
+dist/
+
+# Unit test / coverage reports
+.pytest_cache/
+
+# General
+.DS_Store
+
+# IntelliJ project files
+.idea
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject

LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2021--2022, Scientific Python project
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

README.md

@@ -1,6 +1,36 @@
+![PyPI](https://img.shields.io/pypi/v/yaml2ics?style=for-the-badge)
+
 # YAML to iCalendar (ics)
 
-Please see `example/test_calendar.yaml` for example entries.
+| WARNING: this project is still in beta. Beware of breaking changes! |
+|---------------------------------------------------------------------|
+
+Convert YAML files to .ics files which can be imported into other
+calendar applications.
+
+Features include:
+- Converting single .yaml files, or combining multiple into one .ics
+  file.
+- ics fields: name, summary, description, location, timezone, repeat
+- Specify event start+end or start+duration
+- Recurring events (basic support)
+- All-day events
+- Timezone specification (default or per-event)
+
+## Installation
+
+```
+pip install yaml2ics
+```
+
+**Note:** due to a pending release of a dependency (`ics-py`), an additional
+step is required:
+
+```
+pip install -r requirements.txt
+```
+
+## Usage
 
 To produce a calendar from a list of events:
 
@@ -14,8 +44,49 @@ To combine lists of events in to a calendar:
 python yaml2ics.py example/test_calendar.yaml example/another_calendar.yaml
 ```
 
+## Syntax
+
+Please see `example/test_calendar.yaml` for a full demo including
+explanations.  Below is a minimal template that shows the basic idea:
+
+```yaml
+name: Calendar Name
+timezone: Europe/Helsinki  # default timezone for events, optional
+
+events:
+  - summary: The event title
+    begin: 2021-09-21 15:00:00
+    duration:
+      minutes: 30
+    location: |
+      https://meet.jit.si/example
+    description: |
+      In this meeting we will ...
+```
+
+## Contributing
+
+Contributions are welcomed! This project is still in active development
+and should be considered beta.
+
+To install the development version, fork the source of the project and make an
+editable install:
+
+```
+pip install -r requirements.txt  # temporary workaround for ics-py
+pip install -e ".[test]"
+```
+
 To test:
 
 ```
-PYTHONPATH=. pytest
+pytest
 ```
+
+[black](https://github.com/psf/black) and other linters are used to auto-format
+files (and enforced by CI). To install the git hooks, use `pre-commit install`.
+To run the tests/auto-formatting manually, use `pre-commit run
+--all-files`.
+
+Releases are automatically pushed on PyPi by the CI when pushing a tag
+following `*.*`.

example/test_calendar.yaml

@@ -1,20 +1,34 @@
 name: Test Calendar
 timezone: America/Los_Angeles
+# # Include another list of events in with these.  Note you can also do
+# # this from the command line.
+# include:
+#   - other_calender.ics
 
 events:
   - summary: Event of the Century
-    begin: 2021-09-21 15:00:00
-    end: 2021-09-21 15:30:00
-    description: |
-      Meet the team on the northern side of the field.
-
-  - summary: Half-an-hour meeting
-    begin: 2021-09-23 15:00:00 -07:00
+    begin: 2021-09-21 15:00:00         # uses default timezone above
     duration:
       minutes: 30
+    description: |
+      Meet the team on the northern side of the field.
     location: |
       Office 224, Monolith Bldg, Office Block C
 
+  - summary: Half-an-hour meeting
+    begin: 2021-09-23 15:00:00 -07:00  # explicit timezone offset
+    end: 2021-09-23 15:30:00 -07:00    # explicit timezone offset
+
+  - summary: Recurring event
+    begin: 2022-02-21 15:00:00
+    duration: {minutes: 60}
+    repeat:
+      interval:
+        # seconds, minutes, hours, days, weeks, months, years
+        weeks: 1
+      until: 2022-12-31  # required
+
+  # All-day event
   - summary: Earth Day
     begin: 2021-04-22
     url: https://earthday.org

pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["flit_core >=3.3,<4"]
+build-backend = "flit_core.buildapi"
+
+[project]
+name = "yaml2ics"
+version = "0.1rc1"
+requires-python = ">=3.8"
+authors = [{name = "The Scientific Python Group"}]
+readme = "README.md"
+license = {file = "LICENSE"}
+classifiers = ["License :: OSI Approved :: BSD License"]
+dynamic = ["description"]
+
+dependencies = [
+#    "ics >=0.8",
+    "python-dateutil",
+    "pyyaml",
+]
+
+[project.optional-dependencies]
+test = [
+    "pytest",
+    "black",
+    "pre-commit",
+    "flake8"
+]
+
+[project.scripts]
+yaml2ics = "yaml2ics:main"
+
+[project.urls]
+Home = "https://github.com/scientific-python/yaml2ics"
+Source = "https://github.com/scientific-python/yaml2ics"
+
+[tool.flit.sdist]
+exclude = ["tests/*"]

requirements.txt

@@ -1,3 +1 @@
 https://github.com/ics-py/ics-py/archive/refs/heads/main.zip
-python-dateutil
-pyyaml

yaml2ics.py

@@ -1,3 +1,9 @@
+"""
+yaml2ics
+========
+
+CLI to convert yaml into ics.
+"""
 import os
 import sys
 from datetime import datetime, tzinfo
@@ -135,7 +141,7 @@ def files_to_calendar(files: list) -> ics.Calendar:
     return calendar
 
 
-if __name__ == "__main__":
+def main():
     if len(sys.argv) < 2:
         print("Usage: yaml2ics.py FILE1.yaml FILE2.yaml ...")
         sys.exit(-1)
@@ -149,3 +155,7 @@ def files_to_calendar(files: list) -> ics.Calendar:
     calendar = files_to_calendar(files)
 
     print(calendar.serialize())
+
+
+if __name__ == "__main__":
+    main()