Merge branch 'release/v0.19.0'

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.7", "3.8", "3.9", "3.10"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
     - uses: actions/checkout@v3
     - name: Set up Python ${{ matrix.python-version }}
@@ -22,7 +22,7 @@ jobs:
         python -m pip install flake8
         python -m pip install .
     - name: Run tests
-      run: python setup.py test
+      run: python3 -m unittest
 
   type-checker:
     runs-on: ubuntu-latest
@@ -35,9 +35,10 @@ jobs:
         python -m pip install --upgrade pip
         python -m pip install .
         python -m pip install mypy
-        python -m pip install types-atomicwrites
+        # vobject does fancy dynamic stuff that is hard to type-check
+        python -m pip install types-atomicwrites # types-vobject
     - name: Run the type checker
-      run: mypy --ignore-missing-imports khard
+      run: mypy
 
   docs:
     runs-on: ubuntu-latest
@@ -53,87 +54,3 @@ jobs:
       run: |
         python setup.py build
         make -C doc html man
-
-
-#
-#
-##-------------------------------------- python package
-#
-## This workflow will install Python dependencies, run tests and lint with a variety of Python versions
-## For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-#  Python-package-build:
-#
-#    runs-on: ubuntu-latest
-#    strategy:
-#      fail-fast: false
-#      matrix:
-#        python-version: ["3.8", "3.9", "3.10"]
-#
-#    steps:
-#    - uses: actions/checkout@v2
-#    - name: Set up Python ${{ matrix.python-version }}
-#      uses: actions/setup-python@v2
-#      with:
-#        python-version: ${{ matrix.python-version }}
-#    - name: Install dependencies
-#      run: |
-#        python -m pip install --upgrade pip
-#        python -m pip install flake8
-#        python -m pip install .
-#    - name: Lint with flake8
-#      run: |
-#        # stop the build if there are Python syntax errors or undefined names
-#        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-#        # exit-zero treats all errors as warnings.
-#        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-#    - name: Run tests
-#      run: python setup.py test
-#
-##-------------------------------------- python app
-#
-## This workflow will install Python dependencies, run tests and lint with a single version of Python
-## For more information see: https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
-#  Python-application-build:
-#
-#    runs-on: ubuntu-latest
-#
-#    steps:
-#    - uses: actions/checkout@v2
-#    - name: Set up Python 3.10
-#      uses: actions/setup-python@v2
-#      with:
-#        python-version: "3.10"
-#    - name: Install dependencies
-#      run: |
-#        python -m pip install --upgrade pip
-#        pip install flake8 pytest
-#        if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-#    - name: Lint with flake8
-#      run: |
-#        # stop the build if there are Python syntax errors or undefined names
-#        flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-#        # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
-#        flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-#    - name: Test with pytest
-#      run: |
-#        pytest
-#
-##-------------------------------------- python lint
-#  Pylint-build:
-#    runs-on: ubuntu-latest
-#    strategy:
-#      matrix:
-#        python-version: ["3.8", "3.9", "3.10"]
-#    steps:
-#    - uses: actions/checkout@v2
-#    - name: Set up Python ${{ matrix.python-version }}
-#      uses: actions/setup-python@v2
-#      with:
-#        python-version: ${{ matrix.python-version }}
-#    - name: Install dependencies
-#      run: |
-#        python -m pip install --upgrade pip
-#        pip install pylint
-#    - name: Analysing the code with pylint
-#      run: |
-#        pylint $(git ls-files '*.py')

CHANGES

@@ -1,6 +1,21 @@
 Change Log
 ==========
 
+v0.19.0: 2023-11-23
+
+- Remove support for python 3.7
+- Run tests on python 3.11 and 3.12 in CI
+- Fix yaml conversion of multiple addresses with same label (#323, #324)
+- Improve error message for address book paths (884f1d9)
+- Add pyproject.toml file and deprecate setup.py
+- Remove deprecated options from --help and zsh completion
+- Internal changes:
+  - Add a general ask() function (#320, #326)
+  - Use an exception to cancle user interactions (#325)
+  - More and stricter type hints
+  - Promote AddressBookCollection to a Sequence
+
+
 v0.18.0: 2022-12-10
 - Move project home on GitHub from @scheibler to @lucc
 - Catch exceptions when loading the config (#294)
@@ -53,7 +68,7 @@ v0.15.0: 2019-10-24
 - handle ABLABELs on most fields
 - add formatted name to the yaml template
 - show formatted name in contact details
-- make it possible to sort by and display formatted name in linstings
+- make it possible to sort by and display formatted name in listings
 - remove the khard-runner.py helper script
 - validate the config file upon loading it
 - internal code refactoring
@@ -64,7 +79,7 @@ v0.14.0: 2019-06-21
 - Allow vcard selections to be aborted explicitly
 - Unify edit and source subcommands
 - Merge export and show subcommands
-- Turn template export into a seperate command
+- Turn template export into a separate command
 - Require python >= 3.5
 - Add html documentation (generated with sphinx)
 - Add man page (generated with sphinx)
@@ -138,7 +153,7 @@ v0.11.0: 2016-07-17
     --skip-unparsable to skip unparsable vcard files (#75)
     --strict-search to narrow the contact search to the name field
 - Added some aliases for program actions (#65)
-- Removed davcontroler module due to the python3 incompatibility (script moved into the misc folder)
+- Removed davcontroller module due to the python3 incompatibility (script moved into the misc folder)
 - Updated zsh completion function and khards example config file
 
 
@@ -183,11 +198,11 @@ v0.7.3: 2016-01-08
 
 
 v0.7.2: 2016-01-03
-- Use of module atomicwrites to securely write vcards to disk
+- Use of module atomicwrites to securely write vCards to disk
 
 
 v0.7.1: 2016-01-01
-- Added support for multiple instances of one vcard attribute
+- Added support for multiple instances of one vCard attribute
 
 
 v0.7.0: 2015-12-18

CONTRIBUTING.rst

@@ -23,7 +23,7 @@ easier for maintainers to help:
 - report the version(s) that are affected
 - state the python version you are using
 - if there are stack tracebacks post them with your bug report
-- supply a minimal configuration (config file and vcards) to reproduce the
+- supply a minimal configuration (config file and vCards) to reproduce the
   error
 
 Feature requests
@@ -47,28 +47,39 @@ Please stick to the following standards when you open pull requests:
 Development
 -----------
 
-In order to start coding you need to fetch the develop branch:
+In order to start coding you need to fetch the ``develop`` branch:
 
 .. code-block:: shell
 
   git clone https://github.com/lucc/khard
   cd khard
-  python setup.py build  # to generate the version.py file
-  python -m khard --help
-  # or
+
+It is recommended to create a `virtualenv`_ to isolate the development
+environment for Khard from your system's Python installation:
+
+.. code-block:: shell
+
+  python3 -m venv khard-dev-venv
+  . khard-dev-venv/bin/activate
+
+The you can install the dependencies with ``pip``:
+
+.. code-block:: shell
+
   pip3 install --editable .
   khard --help
 
-Alternatively you can use the ``setup.py`` script directly.  If you want to
-isolate khard from your system Python environment you can use a `virtualenv`_
-to do so.
+If you have the `Nix`_ package manager installed you can use the ``flake.nix``
+that is provided with Khard.  It provides an isolated Python version with all
+dependencies with ``nix develop``.
 
 .. _bug reports: https://github.com/lucc/khard/issues
 .. _the Git book: https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines
 .. _develop: https://github.com/lucc/khard/tree/develop
 .. _feature requests: https://github.com/lucc/khard/pulls
 .. _Github: https://github.com/lucc/khard
 .. _master: https://github.com/lucc/khard/tree/master
+.. _Nix: https://nixos.org
 .. _PEP 8: https://www.python.org/dev/peps/pep-0008/
 .. _pylint: https://pylint.readthedocs.io/en/latest/
 .. |travis| image:: https://github.com/lucc/khard/actions/workflows/ci.yml/badge.svg

README.md

@@ -8,13 +8,13 @@ can find more information about khard and the whole synchronization process
 [here][blog].
 
 Warning: If you want to create or modify contacts with khard, beware that the
-vcard standard is very inconsistent and lacks interoperability. Different
+vCard standard is very inconsistent and lacks interoperability. Different
 actors in that sector have defined their own extensions and even produce
 non-standard output. A good example is the type value, which is tied to phone
 numbers, email and post addresses. Khard tries to avoid such incompatibilities
 but if you sync your contacts with an Android or iOS device, expect problems.
 You are on the safe side, if you only use khard to read contacts. For further
-information about the vcard compatibility issues have a look into [this blog
+information about the vCard compatibility issues have a look into [this blog
 post][sad].
 
 Installation

doc/source/commandline.rst

@@ -140,16 +140,16 @@ Assuming the user had configured the three supported private object "Jabber",
 "Skype", and "Twitter" in their config, the template would look :download:`like
 this <examples/template.yaml>`.
 
-Per default khard creates vcards of version 3.0. If your other contact
-applications support vcards of the more recent version 4.0, you may change this
+Per default khard creates vCards of version 3.0. If your other contact
+applications support vCards of the more recent version 4.0, you may change this
 with the option :option:`--vcard-version`. Example:
 
 .. code-block:: shell
 
    khard new --vcard-version=4.0
 
 For a more permanent solution you may set the preferred_version parameter in
-the vcard section of the khard config file (see the :download:`example config
+the vCard section of the khard config file (see the :download:`example config
 file <examples/khard.conf.example>` for more details).  But beware, that khard
 cannot convert already existing contacts from version 3.0 to 4.0. Therefore
 this setting is not applicable to the modify action.

doc/source/man.rst

@@ -1,5 +1,5 @@
-Manpages
-========
+Man pages
+=========
 
 The following man pages are available for khard:
 

doc/source/man/khard.conf.rst

@@ -41,9 +41,9 @@ addressbooks
   This section contains several subsections, but at least one. Each subsection
   can have an arbitrary name which will be the name of an addressbook known to
   khard.  Each of these subsections **must** have a *path* key with the path to
-  the folder containing the vcard files for that addressbook.  The *path* value
+  the folder containing the vCard files for that addressbook.  The *path* value
   supports environment variables and tilde prefixes.  :program:`khard` expects
-  the vcard files to hold only one VCARD record each and end in a :file:`.vcf`
+  the vCard files to hold only one VCARD record each and end in a :file:`.vcf`
   extension.
 
 general
@@ -80,11 +80,11 @@ contact table
 vcard
   - *private_objects*: a list of strings, these are the names of private vCard
     fields (starting with ``X-``)  that will be loaded and displayed by khard
-  - *search_in_source_files*: whether to search in the vcard files before
+  - *search_in_source_files*: whether to search in the vCard files before
     parsing them in order to speed up searches
-  - *skip_unparsable*: whether to skip unparsable vcards, otherwise khard exits
-    on the first unparsable card it encounters
-  - *preferred_version*: the preferred vcard version to use for new cards
+  - *skip_unparsable*: whether to skip unparsable vCards, otherwise khard
+    exits on the first unparsable card it encounters
+  - *preferred_version*: the preferred vCard version to use for new cards
 
 Example
 -------

doc/source/man/khard.rst

@@ -121,7 +121,7 @@ Spaces in the field name have to be replaced with underscores.
 The available fields are the same fields as in the YAML template with the
 exception of the five name components (first, last, prefix, suffix,
 additional).  But there is the special pseudo field specifier ``name:`` which
-will search in *any* name related field (including nichnames and formatted
+will search in *any* name related field (including nicknames and formatted
 names).
 
 If a field name is not known the search term is interpreted as a plain search

doc/source/scripting.rst

@@ -53,6 +53,22 @@ extension.
 
 .. _vdirsyncer: https://github.com/pimutils/vdirsyncer/
 
+If you already have ``.vcf`` files containing multiple ``VCARD`` entries (i.e.
+from Android/MacOS Contacts app), below are some scripts that 
+generate the corresponding single entry ``.vcf`` files:
+
+* `vcardtool`_ (processes one input file at a time)
+* `vcf-splitter`_ (needs to be used with the ``-u``/``--uid`` flag to generate 
+  the required UID entry)
+
+.. _vcardtool: https://github.com/jakeogh/vcardtool/
+.. _vcf-splitter: https://framagit.org/rogarb/vcf-splitter/
+
+You might need to preparse your ``.vcf`` input files with `vcard2to3`_ if they
+contain ``VERSION:2.1`` entries.
+
+.. _vcard2to3: https://github.com/jowave/vcard2to3
+
 vdirsyncer
 ----------