apq 0.10.0

Description:

apq 0.10.0

apq





apq implements different variants of addressable priority queue data
structures importable from Python 3 projects.
The project aims to provide run-time efficient implementations of priority
queues whilst remaining practical in use and maintaining a legible code base.


All priority queues provided by apq are backed by a C++ binary heap
implementation. The priority queue types exposed to Python are implemented
in Cython.


apq has no installation or runtime dependencies on all common platforms.
Note: A compiler and basic C++ headers are required on platforms for
which no binary distribution of apq is available.


Type stubs are installed along with the package so that mypy can fully
check dependent code.


Priority Queue Types
These priority queues use 64 bit floating point as priority values (value)
and FIFO semantic for entries with the same value. Note: 64 bit floats
can represent 54 bit signed integers.


AddressablePQ - Not implemented. This priority queue exposes
persistent references in the form of Item its entries. Through Item,
the value of entries can be changed and arbitrary entries can be removed
from the PQ.


KeyedPQ - This priority queue allows lookup of entries through a string
key. That means it combines an addressable priority queue with a
dictionary, creating a str to item mapping (almost implementing
typing.Mapping[str, KeyedItem]). KeyedPQ is recommended whenever
individual entries are looked up using a key.


SimplePQ - Not implemented. This priority queue is a non-addressable
variant of AddressablePQ. SimplePQ is recommended when a fast PQ is
required which is only modified via add() and pop().


Quickstart
Installation:
$ pip install apq

Usage:
>>> from apq import KeyedPQ
>>> pq: KeyedPQ[None] = KeyedPQ()
>>> pq.add('my_first_key', 34.0, None)
<apq.Item object at 0x7f506884bd70>
>>> pq.add('my_second_key', 36.0, None)
<apq.Item object at 0x7f506884bcb0>
>>> pq.change_value('my_second_key', 12.0)
<apq.Item object at 0x7f50663604f0>
>>> print(pq.pop())
('my_second_key', 12.0, None)

Releases and Compatibility
apq uses semantic versioning to derive the version identifier of
releases. Code using the documented public API of apq will continue to work
with all future releases of apq which are API compatible. API compatibility
is indicated through the major component of the version identifier.
apq is currently under active development / in beta. Breaking changes of the
public interface will occur. Beta releases are indicated through a 0 in the
major component of the version identifier, e.g. 0.10.0.
To encourage use during beta, apq extends semantic versioning to beta
releases as follows: From 0.10.0 onwards, API compatibility is guaranteed
for all future releases with the same MINOR // 10 value. E.g. 0.17.3 is
API compatible with 0.10.1.
Depending packages should use this semantic for specifying version
constraints, e.g. apq >= 0.11.1, < 0.20.0 (c.f. PEP 508). Pinning
is still recommended for applications, e.g. using Poetry or
Pipenv.
apq aims to fully work on all active versions of Python. Python 3.5 is not
supported at the moment. Information on the state of Python releases is
described in the Python Developer's Guide with further
details on the Development Cycle page.
Distribution
apq is distributed through PyPi. The PyPi apq Project
contains a source distribution for each release. Additionally, pre-built
binary distribution in the form of wheels are available for common platforms.
pip install apq will automatically detect the most appropriate distribution.
TODO: Table of machine platform and OS, Python implementation and version for
which wheels are built.