merge master

Author: Evidlo

.github/workflows/ci.yaml

@@ -4,25 +4,40 @@ on: [push, pull_request, workflow_dispatch]
 
 jobs:
   tests:
-    runs-on: ubuntu-latest
+    name: ${{ matrix.os }}-latest / ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}-latest
     strategy:
-      matrix:
-        python-version: [3.6, 3.7, 3.8, 3.9]
       fail-fast: false
+      matrix:
+        os:
+          - ubuntu
+          # - windows
+          # - macos
+        python-version:
+          # - "3.6" # not supported in ubuntu-latest (22.04)
+          # - "3.7" # not supported in ubuntu-latest ()
+          - "3.8"
+          - "3.9"
+          - "3.10"
+          - "3.11"
+          - "3.12"
+      
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
+          cache: pip
+          allow-prereleases: true
 
       - name: Install dependencies
         run: |
           sudo apt update
           sudo apt-get install -y libxml2-dev libxmlsec1-dev
           python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          pip install .[test]
 
       - name: Run tests
         run: |

.gitignore

@@ -4,6 +4,11 @@ dist/
 *.egg-info/
 build/
 *.xml
+Pipfile
 Pipfile.lock
 *.kdbx
 *.kdbx.out
+.idea
+.venv*
+TMPNOTES
+docs/

CHANGELOG.rst

@@ -1,16 +1,48 @@
-4.0.4 -
+4.1.1 - 2025-03-04
+------------------
+- fixed #410 - support empty string as password
+
+4.1.0 - 2024-06-26
+------------------
+- merged #389 - add PyKeePass.database_name and database_description
+- merged #392, fixed #390 - fix pkg_resources dependency issue
+- fixed #391 - Entry.tags returns empty list instead of None
+- fixed #395 - set 'encoding' attribute when exporting as XML
+- fixed #383 - parse datetimes using isoformat instead of strptime
+
+4.0.7 - 2024-02-29
+------------------
+- fixed #359 - PyKeePass has `decrypt` kwarg for accessing header info
+- merged #347 - added Entry.index and Entry.move for moving entries
+- merged #367 - added Entry.autotype_window setter
+- merged #364 - allow filename/keyfile to be file-like objects
+- merged #371 - drop dateutil dependency
+- merged #348 - switch to pyproject.toml
+
+4.0.6 - 2023-08-22
+------------------
+- fixed #350 - fixed all Python 2 deprecation FIXMEs (e.g. future, )
+
+4.0.5 - 2023-06-05
+------------------
+- fixed #344 - AttributeError when accessing Times with None value
+- use __hash__ when evaluating equality
+- use mtime/uuid for HistoryEntry hashing
+
+4.0.4 - 2023-05-23
 ------------------
 - fixed #314 - correctly handle binaries with no data
 - fixed #265 - check for keepass signature
 - fixed #319 - support pathlib for filename/keyfile
 - fixed #194 - added 'protected' arg to _set_string_field
 - use official icon names from KeePass source and deprecate old icons
 - added Entry.is_custom_property_protected()
+- fixed #338 - allow comma entry tag separator
 
 4.0.3 - 2022-06-21
 ------------------
-- add otp support
-- add debug_setup() function
+- added otp support
+- added debug_setup() function
 
 4.0.2 - 2022-05-21
 ------------------

Makefile

@@ -1,14 +1,50 @@
-version := $(shell python -c "exec(open('pykeepass/version.py').read());print(__version__)")
+.ONESHELL:
+.SHELLFLAGS = -ec
+.SILENT:
+version := $(shell python -c "import tomllib;print(tomllib.load(open('pyproject.toml', 'rb'))['project']['version'])")
 
 .PHONY: dist
 dist:
-	python setup.py sdist bdist_wheel
+	python -m build
 
-.PHONY: pypi
-pypi: dist
-	twine upload dist/pykeepass-$(version).tar.gz
+.PHONY: release
+release: lock dist
+	# check that changelog is updated.  only look at first 3 parts of semver
+	version=$(version)
+	stripped=$$(echo $${version} | cut -d . -f -3 | cut -d '-' -f 1)
+	if ! grep $${stripped} CHANGELOG.rst
+	then
+		echo "Changelog doesn't seem to be updated! Quitting..."
+		exit 1
+	fi
+	# generate release notes from changelog
+	awk "BEGIN{p=0}; /^$${stripped}/{next}; /---/{p=1;next}; /^$$/{exit}; p {print}" CHANGELOG.rst > TMPNOTES
+	# make github and pypi release
+	gh release create --latest --verify-tag v$(version) dist/pykeepass-$(version)* -F TMPNOTES
+	twine upload -u __token__ dist/pykeepass-$(version)*
+
+.PHONY: lock
+lock:
+	# run tests then make a requirements.txt lockfile
+	rm -rf .venv_lock
+	virtualenv .venv_lock
+	. .venv_lock/bin/activate
+	pip install .[test]
+	python tests/tests.py
+	pip freeze > requirements.txt
+
+.PHONY: tag
+tag:
+	# tag git commit
+	git add requirements.txt
+	git add pyproject.toml
+	git add CHANGELOG.rst
+	git commit -m "bump version" --allow-empty
+	git tag -a v$(version) -m "version $(version)"
+	git push --tags
+	git push
 
 .PHONY: docs
 docs:
-	lazydocs pykeepass --overview-file README.md
+	pdoc -o docs --docformat google --no-search pykeepass '!pykeepass.icons' --footer-text "pykeepass ${version}"
 	ghp-import -f -p -b docs docs

README.md

@@ -0,0 +1,216 @@
+# pykeepass
+
+<a href="https://github.com/libkeepass/pykeepass/actions/workflows/ci.yaml"><img src="https://github.com/libkeepass/pykeepass/actions/workflows/ci.yaml/badge.svg"/></a>
+<a href="https://libkeepass.github.io/pykeepass"><img src="https://readthedocs.org/projects/pykeepass/badge/?version=latest"/></a>
+<a href="https://matrix.to/#/%23pykeepass:matrix.org"><img src="https://img.shields.io/badge/chat-%23pykeepass-green"/></a>
+    
+This library allows you to write entries to a KeePass database.
+
+Come chat at [#pykeepass:matrix.org](https://matrix.to/#/%23pykeepass:matrix.org) on Matrix.
+
+# Installation
+
+``` bash
+sudo apt install python3-lxml
+pip install pykeepass
+```
+
+# Quickstart
+
+General database manipulation
+
+``` python
+from pykeepass import PyKeePass
+
+# load database
+>>> kp = PyKeePass('db.kdbx', password='somePassw0rd')
+
+# get all entries
+>>> kp.entries
+[Entry: "foo_entry (myusername)", Entry: "foobar_entry (myusername)", ...]
+
+# find any group by its name
+>>> group = kp.find_groups(name='social', first=True)
+
+# get the entries in a group
+>>> group.entries
+[Entry: "social/facebook (myusername)", Entry: "social/twitter (myusername)"]
+
+# find any entry by its title
+>>> entry = kp.find_entries(title='facebook', first=True)
+
+# retrieve the associated password and OTP information
+>>> entry.password
+'s3cure_p455w0rd'
+>>> entry.otp
+otpauth://totp/test:lkj?secret=TEST%3D%3D%3D%3D&period=30&digits=6&issuer=test
+
+# update an entry
+>>> entry.notes = 'primary facebook account'
+
+# create a new group
+>>> group = kp.add_group(kp.root_group, 'email')
+
+# create a new entry
+>>> kp.add_entry(group, 'gmail', 'myusername', 'myPassw0rdXX')
+Entry: "email/gmail (myusername)"
+
+# save database
+>>> kp.save()
+```
+
+Finding and manipulating entries
+
+``` python
+# add a new entry to the Root group
+>>> kp.add_entry(kp.root_group, 'testing', 'foo_user', 'passw0rd')
+Entry: "testing (foo_user)"
+
+# add a new entry to the social group
+>>> group = kp.find_groups(name='social', first=True)
+>>> entry = kp.add_entry(group, 'testing', 'foo_user', 'passw0rd')
+Entry: "testing (foo_user)"
+
+# save the database
+>>> kp.save()
+
+# delete an entry
+>>> kp.delete_entry(entry)
+
+# move an entry
+>>> kp.move_entry(entry, kp.root_group)
+
+# save the database
+>>> kp.save()
+
+# change creation time
+>>> from datetime import datetime, timezone
+>>> entry.ctime = datetime(2023, 1, 1, tzinfo=timezone.utc)
+
+# update modification or access time
+>>> entry.touch(modify=True)
+
+# save entry history
+>>> entry.save_history()
+```
+
+Finding and manipulating groups
+
+``` python
+>>> kp.groups
+[Group: "foo", Group "foobar", Group: "social", Group: "social/foo_subgroup"]
+
+>>> kp.find_groups(name='foo', first=True)
+Group: "foo"
+
+>>> kp.find_groups(name='foo.*', regex=True)
+[Group: "foo", Group "foobar"]
+
+>>> kp.find_groups(path=['social'], regex=True)
+[Group: "social", Group: "social/foo_subgroup"]
+
+>>> kp.find_groups(name='social', first=True).subgroups
+[Group: "social/foo_subgroup"]
+
+>>> kp.root_group
+Group: "/"
+
+# add a new group to the Root group
+>>> group = kp.add_group(kp.root_group, 'social')
+
+# add a new group to the social group
+>>> group2 = kp.add_group(group, 'gmail')
+Group: "social/gmail"
+
+# save the database
+>>> kp.save()
+
+# delete a group
+>>> kp.delete_group(group)
+
+# move a group
+>>> kp.move_group(group2, kp.root_group)
+
+# save the database
+>>> kp.save()
+
+# change creation time
+>>> from datetime import datetime, timezone
+>>> group.ctime = datetime(2023, 1, 1, tzinfo=timezone.utc)
+
+# update modification or access time
+>>> group.touch(modify=True)
+```
+
+Attachments
+
+``` python
+>>> e = kp.add_entry(kp.root_group, title='foo', username='', password='')
+
+# add attachment data to the db
+>>> binary_id = kp.add_binary(b'Hello world')
+
+>>> kp.binaries
+[b'Hello world']
+
+# add attachment reference to entry
+>>> a = e.add_attachment(binary_id, 'hello.txt')
+>>> a
+Attachment: 'hello.txt' -> 0
+
+# access attachments
+>>> a
+Attachment: 'hello.txt' -> 0
+>>> a.id
+0
+>>> a.filename
+'hello.txt'
+>>> a.data
+b'Hello world'
+>>> e.attachments
+[Attachment: 'hello.txt' -> 0]
+
+# list all attachments in the database
+>>> kp.attachments
+[Attachment: 'hello.txt' -> 0]
+
+# search attachments
+>>> kp.find_attachments(filename='hello.txt')
+[Attachment: 'hello.txt** -> 0]
+
+# delete attachment reference
+>>> e.delete_attachment(a)
+
+# or, delete both attachment reference and binary
+>>> kp.delete_binary(binary_id**
+```
+
+OTP codes
+
+``` python
+# find an entry which has otp attribute
+>>> e = kp.find_entries(otp='.*', regex=True, first=True)
+>>> import pyotp
+>>> pyotp.parse_uri(e.otp).now()
+799270
+```
+
+
+# Tests and Debugging
+
+Run tests with `python tests/tests.py` or `python tests/tests.py SomeSpecificTest`
+
+Enable debugging when doing tests in console:
+
+``` python
+>>> from pykeepass.pykeepass import debug_setup
+>>> debug_setup()
+>>> kp.entries[0]
+DEBUG:pykeepass.pykeepass:xpath query: //Entry
+DEBUG:pykeepass.pykeepass:xpath query: (ancestor::Group)[last()]
+DEBUG:pykeepass.pykeepass:xpath query: (ancestor::Group)[last()]
+DEBUG:pykeepass.pykeepass:xpath query: String/Key[text()="Title"]/../Value
+DEBUG:pykeepass.pykeepass:xpath query: String/Key[text()="UserName"]/../Value
+Entry: "root_entry (foobar_user)"
+```
+