Merge branch 'master' into seedregen

Author: Evidlo

.gitignore

@@ -6,3 +6,4 @@ build/
 *.xml
 Pipfile.lock
 *.kdbx
+*.kdbx.out

CHANGELOG.rst

@@ -1,6 +1,33 @@
+4.0.4 -
 ------------------
-- added Entry.delete_history
+- 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()
+
+4.0.3 - 2022-06-21
+------------------
+- add otp support
+- add debug_setup() function
+
+4.0.2 - 2022-05-21
+------------------
+- added support for argon2id key derivation function
+- added credential expiry functions
+- fixes #223 - safe saving
+
+4.0.1 - 2021-05-22
+------------------
+- added Entry.delete_history()
 - added HistoryEntry class
+- added Group.touch()
+- support 2.0 keyfiles
+- added PyKeePass.reload()
+- dropped python2 tests
+- fixed #284 - autotype_sequence returns string 'None'
+- fixed #244 - incorrect PKCS padding error
 
 4.0.0 - 2021-01-15
 ------------------

Makefile

@@ -0,0 +1,14 @@
+version := $(shell python -c "exec(open('pykeepass/version.py').read());print(__version__)")
+
+.PHONY: dist
+dist:
+	python setup.py sdist bdist_wheel
+
+.PHONY: pypi
+pypi: dist
+	twine upload dist/pykeepass-$(version).tar.gz
+
+.PHONY: docs
+docs:
+	lazydocs pykeepass --overview-file README.md
+	ghp-import -f -p -b docs docs

README.rst

@@ -22,7 +22,7 @@ Come chat at `#pykeepass`_ on Freenode or `#pykeepass:matrix.org`_ on Matrix.
 .. _#pykeepass\:matrix.org: https://matrix.to/#/%23pykeepass:matrix.org 
 
 Example
---------------
+-------
 .. code:: python
 
    from pykeepass import PyKeePass
@@ -58,12 +58,15 @@ Example
    >>> kp.save()
 
 
+..
+    TODO: add `Entry` and `Group` sections to document attributes of each
+
 Finding Entries
-----------------------
+---------------
 
-**find_entries** (title=None, username=None, password=None, url=None, notes=None, path=None, uuid=None, tags=None, string=None, group=None, recursive=True, regex=False, flags=None, history=False, first=False)
+**find_entries** (title=None, username=None, password=None, url=None, notes=None, otp=None, path=None, uuid=None, tags=None, string=None, group=None, recursive=True, regex=False, flags=None, history=False, first=False)
 
-Returns entries which match all provided parameters, where ``title``, ``username``, ``password``, ``url``, ``notes``, and ``autotype_sequence`` are strings, ``path`` is a list, ``string`` is a dict, ``autotype_enabled`` is a boolean, ``uuid`` is a ``uuid.UUID`` and ``tags`` is a list of strings.  This function has optional ``regex`` boolean and ``flags`` string arguments, which means to interpret search strings as `XSLT style`_ regular expressions with `flags`_.
+Returns entries which match all provided parameters, where ``title``, ``username``, ``password``, ``url``, ``notes``, ``otp``, and ``autotype_sequence`` are strings, ``path`` is a list, ``string`` is a dict, ``autotype_enabled`` is a boolean, ``uuid`` is a ``uuid.UUID`` and ``tags`` is a list of strings.  This function has optional ``regex`` boolean and ``flags`` string arguments, which means to interpret search strings as `XSLT style`_ regular expressions with `flags`_.
 
 .. _XSLT style: https://www.xml.com/pub/a/2003/06/04/tr.html
 .. _flags: https://www.w3.org/TR/xpath-functions/#flags 
@@ -101,14 +104,19 @@ a flattened list of all entries in the database
    'facebook.com'
    >>> entry.title
    'foo_entry'
+   >>> entry.title = 'hello'
 
    >>> group = kp.find_group(name='social', first=True)
    >>> kp.find_entries(title='facebook', group=group, recursive=False, first=True)
    Entry: "social/facebook (myusername)"
 
+   >>> entry.otp
+   otpauth://totp/test:lkj?secret=TEST%3D%3D%3D%3D&period=30&digits=6&issuer=test
+
+
 
 Finding Groups
-----------------------
+--------------
 
 **find_groups** (name=None, path=None, uuid=None, notes=None, group=None, recursive=True, regex=False, flags=None, first=False)
 
@@ -155,12 +163,16 @@ a flattened list of all groups in the database
    Group: "/"
 
 
-Adding Entries
---------------
+Entry Functions
+---------------
 **add_entry** (destination_group, title, username, password, url=None, notes=None, tags=None, expiry_time=None, icon=None, force_creation=False)
 
 **delete_entry** (entry)
 
+**trash_entry** (entry)
+
+move a group to the recycle bin.  The recycle bin is created if it does not exit.  ``entry`` must be an empty Entry.
+
 **move_entry** (entry, destination_group)
 
 where ``destination_group`` is a ``Group`` instance.  ``entry`` is an ``Entry`` instance. ``title``, ``username``, ``password``, ``url``, ``notes``, ``tags``, ``icon`` are strings. ``expiry_time`` is a ``datetime`` instance.
@@ -174,7 +186,7 @@ If ``expiry_time`` is a naive datetime object (i.e. ``expiry_time.tzinfo`` is no
    Entry: "testing (foo_user)"
 
    # add a new entry to the social group
-   >>> group = find_groups(name='social', first=True)
+   >>> group = kp.find_groups(name='social', first=True)
    >>> entry = kp.add_entry(group, 'testing', 'foo_user', 'passw0rd')
    Entry: "testing (foo_user)"
 
@@ -190,12 +202,20 @@ If ``expiry_time`` is a naive datetime object (i.e. ``expiry_time.tzinfo`` is no
    # save the database
    >>> kp.save()
 
-Adding Groups
---------------
+Group Functions
+---------------
 **add_group** (destination_group, group_name, icon=None, notes=None)
 
 **delete_group** (group)
 
+**trash_group** (group)
+
+move a group to the recycle bin.  The recycle bin is created if it does not exit.  ``group`` must be an empty Group.
+
+**empty_group** (group)
+
+delete all entries and subgroups of a group.  ``group`` is an instance of ``Group``.
+
 **move_group** (group, destination_group)
 
 ``destination_group`` and ``group`` are instances of ``Group``.  ``group_name`` is a string
@@ -224,11 +244,11 @@ Adding Groups
 Attachments
 -----------
 
-In this section, *binary* refers to the bytes of the attached data (stored at the root level of the database), while *attachment* is a reference to a binary (stored in an entry).  A binary can have none, one or many attachments.
+In this section, *binary* refers to the bytes of the attached data (stored at the root level of the database), while *attachment* is a reference to a binary (stored in an entry).  A binary can be referenced by none, one or many attachments.
 
 **add_binary** (data, compressed=True, protected=True)
 
-where ``data`` is bytes.  Adds a blob of data to the database. The attachment reference must still be added to an entry (see below).  ``compressed`` only applies to KDBX3 and ``protected`` only applies to KDBX4.  Returns id of attachment.
+where ``data`` is bytes.  Adds a blob of data to the database. The attachment reference must still be added to an entry (see below).  ``compressed`` only applies to KDBX3 and ``protected`` only applies to KDBX4 (no effect if used on wrong database version).  Returns id of attachment.
 
 **delete_binary** (id)
 
@@ -243,7 +263,7 @@ where ``id`` is an int, ``filename`` is a string, and element is an ``Entry`` or
 
 **binaries**
 
-list of bytestrings containing binary data.  List index corresponds to attachment id.
+list of bytestrings containing binary data.  List index corresponds to attachment id
 
 **attachments**
 
@@ -310,13 +330,37 @@ the entry that this attachment is attached to
 
    # search attachments
    >>> kp.find_attachments(filename='hello.txt')
-   [Attachment: 'hello.txt' -> 0]
+   [Attachment: 'hello.txt** -> 0]
 
    # delete attachment reference
    >>> e.delete_attachment(a)
 
    # or, delete both attachment reference and binary
-   >>> kp.delete_binary(binary_id)
+   >>> kp.delete_binary(binary_id**
+
+Credential Expiry
+-----------------
+
+**credchange_date**
+
+datetime object with date of last credentials change
+
+**credchange_required**
+
+boolean whether database credentials have expired and are required to change
+
+**credchange_recommended**
+
+boolean whether database credentials have expired and are recommended to change
+
+**credchange_required_days**
+
+days after **credchange_date** that credential update is required
+
+**credchange_recommended_days**
+
+days after **credchange_date** that credential update is recommended
+
 
 Miscellaneous
 -------------
@@ -326,13 +370,21 @@ where ``filename``, ``password``, and ``keyfile`` are strings.  ``filename`` is
 
 Can raise ``CredentialsError``, ``HeaderChecksumError``, or ``PayloadChecksumError``.
 
+**reload** ()
+
+reload database from disk using previous credentials
+
 **save** (filename=None)
 
 where ``filename`` is the path of the file to save to.  If ``filename`` is not given, the path given in ``read`` will be used.
 
 **password**
 
-string containing database password.  Can also be set.  Use ``None`` for no password.
+string containing database password.  Can also be set.  Use ``None** for no password.
+
+**filename**
+
+string containing path to database.  Can also be set
 
 **keyfile**
 
@@ -350,15 +402,32 @@ string containing algorithm used to encrypt database.  Possible values are ``aes
 
 create a new database at ``filename`` with supplied credentials.  Returns ``PyKeePass`` object
 
-**trash_group** (group)
+**tree**
 
-move a group to the recycle bin.  The recycle bin is created if it does not exit.  ``group`` must be an empty Group.
+database lxml tree
 
-**empty_group** (group)
+**xml**
 
-delete all entries and subgroups of a group.  ``group`` is an instance of ``Group``.
+get database XML data as string
 
-Tests
--------------
+**dump_xml** (filename)
+
+pretty print database XML to file
+
+
+Tests and Debugging
+-------------------
+
+Run tests with :code:`python tests/tests.py` or :code:`python tests/tests.py SomeSpecificTest`
+
+Enable debugging when doing tests in console:
 
-To run them issue :code:`python tests/tests.py`
+   >>> 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)"