Merge pull request #93 from rsb-23/linting/1-add-pre-commit

Adding pre-commit with linters and formatters

Author: da4089

.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text eol=lf

.github/workflows/pre-commit.yml

@@ -0,0 +1,25 @@
+name: pre-commit
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  pre-commit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5.1.1
+        with:
+          python-version: 3.9
+          cache: 'pip'
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install pre-commit
+
+      - name: Run pre-commit
+        env:
+          SKIP: pylint,mypy,no-commit-to-branch
+        run: pre-commit run --all-files

.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+repos:
+  - repo: https://github.com/PyCQA/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+
+  - repo: https://github.com/psf/black
+    rev: 24.10.0
+    hooks:
+      - id: black
+
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-yaml
+      - id: check-toml
+      - id: end-of-file-fixer
+      - id: no-commit-to-branch
+        args: [-b, main, -b, master]
+
+  - repo: https://github.com/PyCQA/flake8
+    rev: 7.1.1
+    hooks:
+      - id: flake8
+        additional_dependencies: [flake8-pyproject]

CHANGELOG.md

@@ -304,11 +304,11 @@ To install, use _easy_install_, or download the archive and untar, run
 _dateutil 1.1_ or later is required.
 Python 2.4 is also required.
 
-  * Tolerate invalid UNTIL values for recurring events
-  * Minor improvements to logging and tracebacks
-  * Fix serialization of zero-delta durations
-  * Treat different tzinfo classes that represent UTC as equal
-  * Added ORG behavior to vCard handling, native value for ORG is now a list.
+* Tolerate invalid UNTIL values for recurring events
+* Minor improvements to logging and tracebacks
+* Fix serialization of zero-delta durations
+* Treat different tzinfo classes that represent UTC as equal
+* Added ORG behavior to vCard handling, native value for ORG is now a list.
 
 vobject 0.4.8 released (SVN revision 180)
 --
@@ -452,6 +452,7 @@ vobject 0.2.3 released (SVN revision 104)
 To install, untar the archive, run `python setup.py install`.
 _dateutil 0.9_ or later is required.
 Python 2.4 is also required.
+
 *
 * Added VERSION line back into native iCalendar objects
 * Added a first stab at a vcard module, parsing of vCard 3.0 files now
@@ -518,8 +519,7 @@ _dateutil_ is required.
 * You'll need to apply this patch to be able to read certain VTIMEZONEs
   exported by Apple iCal, or if you happen to be in Europe!
 
-
-    patch -R $PYTHONLIB/site-packages/dateutil/tz.py dateutil-0.5-tzoffset-bug.patch
+  patch -R $PYTHONLIB/site-packages/dateutil/tz.py dateutil-0.5-tzoffset-bug.patch
 
 * Fixed printing of non-ascii unicode.
 * Fixed bug preventing content lines with empty contents from parsing.
@@ -534,8 +534,7 @@ To install, untar the archive, run `python setup.py install`.
 * You'll need to apply this patch to be able to read certain VTIMEZONEs
   exported by Apple iCal, or if you happen to be in Europe!
 
-
-    patch -R $PYTHONLIB/site-packages/dateutil/tz.py dateutil-0.5-tzoffset-bug.patch
+  patch -R $PYTHONLIB/site-packages/dateutil/tz.py dateutil-0.5-tzoffset-bug.patch
 
 * Various bug fixes involving recurrence.
 * TRIGGER and VALARM behaviors set up.

CONTRIBUTING.md

@@ -6,21 +6,21 @@ Welcome, and thanks for considering contributing to vObject!
 **_This document is an incomplete draft_**
 
 Contributions can take many forms, from coding major features, through
-triaging issues, writing documentation, assisting users, etc, etc.   You
+triaging issues, writing documentation, assisting users, etc, etc. You
 can, of course, just dive right in, but it's generally a good idea to
 open an issue (if the contribution addresses a problem) or a discussion
-to discuss your plans first.  This avoids duplicate effort, and builds
+to discuss your plans first. This avoids duplicate effort, and builds
 the community of contributors.
 
 In all interactions, contributors should be polite, kind, and respectful
-of others.  Remember that not everyone lives in the same country, speaks
+of others. Remember that not everyone lives in the same country, speaks
 English as their native language, or has the same level of experience and
 confidence.
 
 Python Code
 -----------
 vObject is licensed under the Apache 2.0 License, and any code or
-documentation can only be accepted under those terms.  You do _not_ need
+documentation can only be accepted under those terms. You do _not_ need
 a formal statement of origin, and are not required to sign over your
 copyright.
 
@@ -33,5 +33,13 @@ taken to not use features that are unavailable in the older supported
 releases.
 
 With the possible exception of major releases, all contributions must
-maintain the existing API's syntax and semantics.  
+maintain the existing API's syntax and semantics.
 
+Dev Setup
+-
+
+1. Enable pre-commit hook and run manually.
+   ```
+   pre-commit install
+   git add . && pre-commit run
+   ```

README.md

@@ -1,4 +1,5 @@
 # VObject
+
 [![PyPI version](https://badge.fury.io/py/vobject.svg)](https://pypi.python.org/pypi/vobject)
 [![PyPI downloads](https://img.shields.io/pypi/dm/vobject.svg)](https://pypi.python.org/pypi/vobject)
 [![Build](https://github.com/py-vobject/vobject/actions/workflows/test.yml/badge.svg)](https://github.com/py-vobject/vobject/actions/workflows/test.yml)
@@ -15,33 +16,36 @@ The [Calendar Server](http://calendarserver.org/) team has added VAVAILABILITY
 support to VObject's iCalendar parsing.
 
 There are two series of releases:
-* Versions 0.9.x continue to support Python 2.7.  This branch is maintained 
-  only for backward compatibility, and does not get new features.
-* Versions 1.x support only Python 3.8 or later, and is the focus of
-  ongoing feature development.
+
+* Versions 0.9.x continue to support Python 2.7. This branch is maintained only for backward compatibility, and does not
+  get new features.
+* Versions 1.x support only Python 3.8 or later, and is the focus of ongoing feature development.
 
 Please report bugs and issues directly on [GitHub](https://github.com/py-vobject/vobject/issues).
 
 VObject is licensed under the [Apache 2.0 license](http://www.apache.org/licenses/LICENSE-2.0).
 
 Useful scripts included with VObject:
 
-* [ics_diff](https://github.com/py-vobject/vobject/blob/master/vobject/ics_diff.py): order is irrelevant in iCalendar files, return a diff of meaningful changes between icalendar files
-* [change_tz](https://github.com/py-vobject/vobject/blob/master/vobject/change_tz.py): Take an iCalendar file with events in the wrong timezone, change all events or just UTC events into one of the timezones **pytz** supports. Requires [pytz](https://pypi.python.org/pypi/pytz/).
+* [ics_diff](https://github.com/py-vobject/vobject/blob/master/vobject/ics_diff.py): order is irrelevant in iCalendar
+  files, return a diff of meaningful changes between icalendar files
+* [change_tz](https://github.com/py-vobject/vobject/blob/master/vobject/change_tz.py): Take an iCalendar file with
+  events in the wrong timezone, change all events or just UTC events into one of the timezones **pytz** supports.
+  Requires [pytz](https://pypi.python.org/pypi/pytz/).
 
 # History
-VObject was originally developed in concert with the Open Source Application
-Foundation's _Chandler_ project by Jeffrey Harris.  Maintenance was later
-passed to [Sameen Karim](https://github.com/skarim) and
+
+VObject was originally developed in concert with the Open Source Application Foundation's _Chandler_ project by
+Jeffrey Harris. Maintenance was later passed to [Sameen Karim](https://github.com/skarim) and
 [Will Percival](https://github.com/wpercy) at [Eventable](https://github.com/eventable).
-After several years of inactivity, the project was revived under a dedicated
-GitHub organization, with new volunteers.
+After several years of inactivity, the project was revived under a dedicated GitHub organization, with new volunteers.
 
-**Please note**: the original repository at [eventable/vobject](https://github.com/eventable/vobject/)
-is _unmaintained_.  This project forked the latest code from that repository, after
-attempts to revive the existing project with new maintainers were unsuccessful.
+**Please note**: the original repository at [eventable/vobject](https://github.com/eventable/vobject/) is
+_unmaintained_. This project forked the latest code from that repository, after attempts to revive the existing project
+with new maintainers were unsuccessful.
 
-Many thanks to [all the contributors](https://github.com/py-vobject/vobject/blob/master/ACKNOWLEDGEMENTS.txt) for their dedication and support.
+Many thanks to [all the contributors](https://github.com/py-vobject/vobject/blob/master/ACKNOWLEDGEMENTS.txt) for their
+dedication and support.
 
 # Installation
 
@@ -51,15 +55,14 @@ To install with [pip](https://pypi.python.org/pypi/pip), run:
 pip install vobject
 ```
 
-
 Or download the package and run:
 
 ```
 python setup.py install
 ```
 
-VObject requires Python 2.7 or higher, along with the [dateutil](https://pypi.python.org/pypi/python-dateutil/) and [six](https://pypi.python.org/pypi/six) packages.
-
+VObject requires Python 2.7 or higher, along with the [dateutil](https://pypi.python.org/pypi/python-dateutil/)
+and [six](https://pypi.python.org/pypi/six) packages.
 
 # Running tests
 
@@ -69,16 +72,14 @@ To run all tests, use:
 python tests.py
 ```
 
-
 # Usage
 
 ## iCalendar
 
 #### Creating iCalendar objects
 
-VObject has a basic datastructure for working with iCalendar-like
-syntaxes.  Additionally, it defines specialized behaviors for many of
-the commonly used iCalendar objects.
+VObject has a basic datastructure for working with iCalendar-like syntaxes. Additionally, it defines specialized
+behaviors for many of the commonly used iCalendar objects.
 
 To create an object that already has a behavior defined, run:
 
@@ -113,12 +114,10 @@ children:
        SUMMARY: This is a note
 ```
 
-Note that summary is a little different from vevent, it's a
-ContentLine, not a Component.  It can't have children, and it has a
-special value attribute.
+Note that summary is a little different from vevent, it's a ContentLine, not a Component. It can't have children, and it
+has a special value attribute.
 
-ContentLines can also have parameters.  They can be accessed with
-regular attribute names with _param appended:
+ContentLines can also have parameters. They can be accessed with regular attribute names with _param appended:
 
 ```
 >>> cal.vevent.summary.x_random_param = 'Random parameter'
@@ -132,9 +131,8 @@ regular attribute names with _param appended:
 
 There are a few things to note about this example
 
-  * The underscore in x_random is converted to a dash (dashes are
-    legal in iCalendar, underscores legal in Python)
-  * X-RANDOM's value is a list.
+* The underscore in x_random is converted to a dash (dashes are legal in iCalendar, underscores legal in Python)
+* X-RANDOM's value is a list.
 
 If you want to access the full list of parameters, not just the first,
 use <paramname>_paramlist:
@@ -147,7 +145,8 @@ use <paramname>_paramlist:
 <SUMMARY{'X-RANDOM': ['Random parameter', 'Other param']}This is a note>
 ```
 
-Similar to parameters, If you want to access more than just the first child of a Component, you can access the full list of children of a given name by appending _list to the attribute name:
+Similar to parameters, If you want to access more than just the first child of a Component, you can access the full list
+of children of a given name by appending _list to the attribute name:
 
 ```
 >>> cal.add('vevent').add('summary').value = "Second VEVENT"
@@ -202,12 +201,11 @@ END:VCALENDAR
 ```
 
 Observe that serializing adds missing required lines like version and
-prodid.  A random UID would be generated, too, if one didn't exist.
+prodid. A random UID would be generated, too, if one didn't exist.
 
 If dtstart's tzinfo had been something other than UTC, an appropriate
 vtimezone would be created for it.
 
-
 #### Parsing iCalendar objects
 
 To parse one top level component from an existing iCalendar stream or
@@ -228,7 +226,6 @@ datetime.datetime(2006, 2, 16, 0, 0, tzinfo=tzutc())
 
 More examples can be found in source code doctests.
 
-
 ## vCards
 
 #### Creating vCard objects
@@ -307,7 +304,9 @@ u'Harris'
  <EMAIL{'TYPE': ['INTERNET']}jeffery@example.org>]
 ```
 
-Just like with iCalendar example above readComponents will yield a generator from a stream or string containing multiple vCards objects.
+Just like with iCalendar example above readComponents will yield a generator from a stream or string containing multiple
+vCards objects.
+
 ```
 >>> vobject.readComponents(vCardStream).next().email.value
 'jeffrey@osafoundation.org'

ROADMAP.md

@@ -5,14 +5,14 @@ Immediate tasks, starting early 2024
 
 - [ ] Apply all open good PRs
   - Add unit test coverage where missing
-  - Add comments to _eventable_ repo, so people can see they're being 
+  - Add comments to _eventable_ repo, so people can see they're being
     fixed in the _py-vobject_ project
 - [ ] Do a pass through the open issues at _eventable_
   - Fix anything easy
   - Copy the issue over to _py-vobject_ for bigger items that can't be
     fixed right away
 - [ ] Renumber _master_ for 1.0.x
-  - And rename to `main` while we're here? 
+  - And rename to `main` while we're here?
 - [ ] Set up GitHub issue triage, etc
   - Group members and permissions
   - Labels

programmers-guide/source/conf.py

@@ -8,34 +8,34 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 import datetime
+
 import vobject
 
-project = 'Python vObject'
-copyright = f'© {datetime.datetime.now().year}, David Arnold'
-author = 'David Arnold'
+project = "Python vObject"
+copyright = f"© {datetime.datetime.now().year}, David Arnold"
+author = "David Arnold"
 release = vobject.VERSION
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = []
 
-templates_path = ['_templates']
+templates_path = ["_templates"]
 exclude_patterns = []
 
 
-
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'alabaster'
+html_theme = "alabaster"
 
 html_theme_options = {
-    'github_user': 'py-vobject',
-    'github_repo': 'vobject',
-    'github_type': 'star',
-    'github_button': 'true',
-    'github_count': 'true',
+    "github_user": "py-vobject",
+    "github_repo": "vobject",
+    "github_type": "star",
+    "github_button": "true",
+    "github_count": "true",
 }
 
-html_static_path = ['_static']
+html_static_path = ["_static"]