paddles is a pedagogical algorithms and data structures library.\n\nIt currently implements the Stack, Queue and Deque abstract data types (ADTs).
\n\nThe code repository is at https://github.com/dsa-ou/paddles.\nThe formatted documentation is at https://dsa-ou.github.io/paddles.
\n\nLicence
\n\npaddles is Copyright \u00a9 2024 by The Open University, UK.\nThe code is licensed under a BSD-3-clause licence.\nThe documentation is licensed under a\nCreative Commons Attribution 4.0 International Licence.
\n"}, {"fullname": "paddles.deque", "modulename": "paddles.deque", "kind": "module", "doc": "This module implements the Deque ADT.
\n\nIntuition
\n\nThe Deque ADT models a line of objects that can be accessed, added to and\nremoved from either end of the line.\nA deque can be used as a stack or as a queue.
\n\nDefinition
\n\nA deque, pronounced 'deck' and short for 'double-ended queue', is a sequence\nwhere only the members at both ends of the sequence\n(called the front and the back of the queue) can be accessed and removed.\nNew members can only be added at the front or at the back.
\n\nOperations
\n\nThe Deque ADT provides operations to:
\n\n\n- create a new empty deque
\n- add a new member to the front of the deque
\n- add a new member to the back of the deque
\n- remove the member at the front of the deque
\n- remove the member at the back of the deque
\n- access the member at the front of the deque without removing it
\n- access the member at the back of the deque without removing it
\n- compute the size of the deque (number of members).
\n
\n\nApplications
\n\nConsider using a deque when you need to simulate a queue where
\n\n\n- objects jump the queue (join at the front) or\nleave it from the back after waiting a certain time
\n- the direction of the queue changes, like cars on a ferry.
\n
\n\nImplementations
\n\nThe Deque ADT can be implemented with circular dynamic arrays or doubly-linked lists.\nIn both cases, the operations listed above take constant time.\nA doubly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.\npaddles only provides a doubly-linked list implementation for the moment.
\n"}, {"fullname": "paddles.deque.LinkedListDeque", "modulename": "paddles.deque", "qualname": "LinkedListDeque", "kind": "class", "doc": "An implementation of the Deque ADT, using a doubly-linked list.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty deque from a given sequence
\n- convert a deque to a string, to see its members listed from front to back.
\n
\n\n\n
>>> from paddles.deque import LinkedListDeque\n>>> deque = LinkedListDeque("abc") # create a non-empty deque\n>>> deque.size() # number of members\n3\n>>> deque.take_front() # remove and return the front member\n'a'\n>>> deque.take_back() # remove and return the back member\n'c'\n>>> deque.front() == deque.back() == 'b' # return the front and back members\nTrue\n>>> deque.add_back("C") # add a new member at the back\n>>> deque.add_front("A") # add a new member at the front\n>>> print(deque) # str(deque) also possible\nLinkedListDeque(['A', 'b', 'C'])\n
\n
Initialize the deque with the members of sequence.
\n\nThe members are added to the deque in the order they are in sequence.\nTo create an empty deque, call LinkedListDeque() or LinkedListDeque([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.deque.LinkedListDeque.size", "modulename": "paddles.deque", "qualname": "LinkedListDeque.size", "kind": "function", "doc": "Return how many members the deque has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.front", "kind": "function", "doc": "Return the item at the front of the deque, without removing it.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.back", "kind": "function", "doc": "Return the item at the back of the deque, without removing it.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.add_front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.add_front", "kind": "function", "doc": "Put item at the front of the deque.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.add_back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.add_back", "kind": "function", "doc": "Put item at the back of the deque.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.take_front", "modulename": "paddles.deque", "qualname": "LinkedListDeque.take_front", "kind": "function", "doc": "Remove and return the item at the front of the deque.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.deque.LinkedListDeque.take_back", "modulename": "paddles.deque", "qualname": "LinkedListDeque.take_back", "kind": "function", "doc": "Remove and return the item at the back of the deque.
\n\nRaise ValueError if the deque is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.queue", "modulename": "paddles.queue", "kind": "module", "doc": "This module implements the Queue ADT.
\n\nIntuition
\n\nThe Queue ADT models a line of objects, e.g. cars waiting to board a ferry.\nOnly the object at the front of the line can be accessed and removed.\nThe only way to add an object is to put it at the back of the line.
\n\nDefinition
\n\nA queue is a sequence where members are added to one end of the sequence\n(the back of the queue) and removed from the other end (the front of the queue).
\n\nA queue is a first-in, first-out (FIFO) sequence:\nthe members are removed in the same order they were added.
\n\nA queue is a sequence ordered by age (time of addition).\nThe oldest member is at the front of the queue, and the youngest member is at the back.
\n\nOperations
\n\nThe Queue ADT provides operations to:
\n\n\n- create a new empty queue
\n- add a new member, at the back of the existing ones
\n- remove the member at the front of the queue
\n- access the member at the front of the queue without removing it
\n- compute the size of the queue (number of members).
\n
\n\nApplications
\n\nQueues are used to implement breadth-first search.\nYou should consider using a queue when you need to:
\n\n\n- simulate a real-life queue, like travellers at passport control or\ndocuments in a printer queue
\n- process items in the same order they were added, like a to-do list.
\n
\n\nImplementations
\n\nThe Queue ADT can be implemented with circular dynamic arrays or singly-linked lists.\nIn both cases, the operations listed above take constant time.\nA singly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.\npaddles only provides a singly-linked list implementation for the moment.
\n"}, {"fullname": "paddles.queue.LinkedListQueue", "modulename": "paddles.queue", "qualname": "LinkedListQueue", "kind": "class", "doc": "An implementation of the Queue ADT, using a singly-linked list.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty queue from a given sequence
\n- convert a queue to a string, to see its members listed from front to back.
\n
\n\n\n
>>> from paddles.queue import LinkedListQueue\n>>> q = LinkedListQueue("abc") # create a non-empty queue\n>>> q.size() # number of members\n3\n>>> q.dequeue() # remove and return the front member\n'a'\n>>> q.front() # return but don't remove the front member\n'b'\n>>> q.enqueue("d") # add a new member at the back\n>>> print(q) # str(q) also possible\nLinkedListQueue(['b', 'c', 'd'])\n
\n
Initialize the queue with the members of sequence.
\n\nThe members are added to the queue in the order they are in sequence.\nTo create an empty queue, call LinkedListQueue() or LinkedListQueue([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.queue.LinkedListQueue.size", "modulename": "paddles.queue", "qualname": "LinkedListQueue.size", "kind": "function", "doc": "Return how many members the queue has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.front", "modulename": "paddles.queue", "qualname": "LinkedListQueue.front", "kind": "function", "doc": "Return the member at the front of the queue, without removing it.
\n\nRaise ValueError if the queue is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.enqueue", "modulename": "paddles.queue", "qualname": "LinkedListQueue.enqueue", "kind": "function", "doc": "Put item at the back of the queue.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.queue.LinkedListQueue.dequeue", "modulename": "paddles.queue", "qualname": "LinkedListQueue.dequeue", "kind": "function", "doc": "Remove and return the item at the front of the queue.
\n\nRaise ValueError if the queue is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack", "modulename": "paddles.stack", "kind": "module", "doc": "This module implements the Stack ADT.
\n\nIntuition
\n\nThe Stack ADT models a pile of objects, e.g. a pile of storage boxes.\nOnly the object at the top of the pile can be accessed and removed.\nThe only way to add an object is to put it on top of the existing pile.
\n\nDefinition
\n\nA stack is a sequence where members are removed from and added to\nthe same end of the sequence, called the top of the stack.
\n\nA stack is a last-in, first-out (LIFO) sequence:\nthe next member to be removed is the one most recently added.
\n\nA stack is a sequence ordered by age (time of addition).\nThe oldest member is at the bottom of the stack, and the youngest member is at the top.
\n\nOperations
\n\nThe Stack ADT provides operations to:
\n\n\n- create a new empty stack
\n- add a new member, on top of the existing ones
\n- remove the member at the top of the stack
\n- access the member at the top of the stack without removing it
\n- compute the size of the stack (number of members).
\n
\n\nApplications
\n\nStacks are used to implement function calls and depth-first search.\nYou should consider using a stack when you need to:
\n\n\n- simulate the handling of a pile of objects, like loading and unloading ship containers
\n- process nested structures, like brackets (e.g.
print([1, {2, 3}])) or\nHTML tags (e.g. <p><b>text</b></p>) \n- process items in the reverse order they were added, like undo operations\n(the next command to be undone is the most recently executed one).
\n
\n\nImplementations
\n\nThe Stack ADT can be implemented with dynamic arrays or singly-linked lists.\nIn both cases, the operations listed above take constant time.\nA singly-linked list uses much more memory than a static array of the same length,\nbut a dynamic array may have wasted capacity and requires resizing.
\n"}, {"fullname": "paddles.stack.DynamicArrayStack", "modulename": "paddles.stack", "qualname": "DynamicArrayStack", "kind": "class", "doc": "An implementation of the Stack ADT, using Python lists.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty stack from a given sequence
\n- convert a stack to a string, to see its members listed from bottom to top.
\n
\n\n\n
>>> from paddles.stack import DynamicArrayStack\n>>> stack = DynamicArrayStack("abc") # create a non-empty stack\n>>> stack.size() # number of members\n3\n>>> stack.pop() # remove and return the top member\n'c'\n>>> stack.peek() # return but don't remove the top member\n'b'\n>>> stack.push("C") # add a new member on top\n>>> print(stack) # str(stack) also possible\nDynamicArrayStack(['a', 'b', 'C'])\n
\n
Initialize the stack with the members of sequence.
\n\nThe members are added to the stack in the order they are in sequence.\nTo create an empty stack, call DynamicArrayStack() or DynamicArrayStack([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.stack.DynamicArrayStack.size", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.size", "kind": "function", "doc": "Return how many members the stack has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.peek", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.peek", "kind": "function", "doc": "Return the member at the top of the stack, without removing it.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.push", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.push", "kind": "function", "doc": "Put item on top of the stack.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.stack.DynamicArrayStack.pop", "modulename": "paddles.stack", "qualname": "DynamicArrayStack.pop", "kind": "function", "doc": "Remove and return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack", "modulename": "paddles.stack", "qualname": "LinkedListStack", "kind": "class", "doc": "An implementation of the Stack ADT, using singly-linked lists.
\n\nBesides the ADT's operations, this class provides two convenience operations:
\n\n\n- create a non-empty stack from a given sequence
\n- convert a stack to a string, to see its members listed from bottom to top.
\n
\n\n\n
>>> from paddles.stack import LinkedListStack\n>>> stack = LinkedListStack("abc") # create a non-empty stack\n>>> stack.size() # number of members\n3\n>>> stack.pop() # remove and return the top member\n'c'\n>>> stack.peek() # return but don't remove the top member\n'b'\n>>> stack.push("C") # add a new member on top\n>>> print(stack) # str(stack) also possible\nLinkedListStack(['a', 'b', 'C'])\n
\n
Initialize the stack with the members of sequence.
\n\nThe members are added to the stack in the order they are in sequence.\nTo create an empty stack, call LinkedListStack() or LinkedListStack([]).
\n\nComplexity: O(len(sequence))
\n", "signature": "(sequence: collections.abc.Sequence[typing.Any] = [])"}, {"fullname": "paddles.stack.LinkedListStack.size", "modulename": "paddles.stack", "qualname": "LinkedListStack.size", "kind": "function", "doc": "Return how many members the stack has.
\n\nComplexity: O(1)
\n", "signature": "(self) -> int:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.push", "modulename": "paddles.stack", "qualname": "LinkedListStack.push", "kind": "function", "doc": "Put item on top of the stack.
\n\nComplexity: O(1)
\n", "signature": "(self, item: Any) -> None:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.pop", "modulename": "paddles.stack", "qualname": "LinkedListStack.pop", "kind": "function", "doc": "Remove and return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}, {"fullname": "paddles.stack.LinkedListStack.peek", "modulename": "paddles.stack", "qualname": "LinkedListStack.peek", "kind": "function", "doc": "Return the member at the top of the stack.
\n\nRaise ValueError if the stack is empty.
\n\nComplexity: O(1)
\n", "signature": "(self) -> Any:", "funcdef": "def"}];
+
+ // mirrored in build-search-index.js (part 1)
+ // Also split on html tags. this is a cheap heuristic, but good enough.
+ elasticlunr.tokenizer.setSeperator(/[\s\-.;&_'"=,()]+|<[^>]*>/);
+
+ let searchIndex;
+ if (docs._isPrebuiltIndex) {
+ console.info("using precompiled search index");
+ searchIndex = elasticlunr.Index.load(docs);
+ } else {
+ console.time("building search index");
+ // mirrored in build-search-index.js (part 2)
+ searchIndex = elasticlunr(function () {
+ this.pipeline.remove(elasticlunr.stemmer);
+ this.pipeline.remove(elasticlunr.stopWordFilter);
+ this.addField("qualname");
+ this.addField("fullname");
+ this.addField("annotation");
+ this.addField("default_value");
+ this.addField("signature");
+ this.addField("bases");
+ this.addField("doc");
+ this.setRef("fullname");
+ });
+ for (let doc of docs) {
+ searchIndex.addDoc(doc);
+ }
+ console.timeEnd("building search index");
+ }
+
+ return (term) => searchIndex.search(term, {
+ fields: {
+ qualname: {boost: 4},
+ fullname: {boost: 2},
+ annotation: {boost: 2},
+ default_value: {boost: 2},
+ signature: {boost: 2},
+ bases: {boost: 2},
+ doc: {boost: 1},
+ },
+ expand: true
+ });
+})();
\ No newline at end of file
diff --git a/paddles/__init__.py b/paddles/__init__.py
index e69de29..2a87b56 100644
--- a/paddles/__init__.py
+++ b/paddles/__init__.py
@@ -0,0 +1,14 @@
+"""`paddles` is a pedagogical algorithms and data structures library.
+
+It currently implements the Stack, Queue and Deque abstract data types (ADTs).
+
+The code repository is at https://github.com/dsa-ou/paddles.
+The formatted documentation is at https://dsa-ou.github.io/paddles.
+
+## Licence
+
+`paddles` is Copyright © 2024 by The Open University, UK.
+The code is licensed under a [BSD-3-clause licence](https://github.com/dsa-ou/paddles/blob/main/LICENSE).
+The documentation is licensed under a
+[Creative Commons Attribution 4.0 International Licence](http://creativecommons.org/licenses/by/4.0).
+"""
diff --git a/paddles/deque.py b/paddles/deque.py
index 6d66a54..2f985e6 100644
--- a/paddles/deque.py
+++ b/paddles/deque.py
@@ -1,6 +1,51 @@
+"""This module implements the Deque ADT.
+
+## Intuition
+
+The Deque ADT models a line of objects that can be accessed, added to and
+removed from either end of the line.
+A deque can be used as a [stack](stack.html) or as a [queue](queue.html).
+
+## Definition
+
+A **deque**, pronounced 'deck' and short for 'double-ended queue', is a sequence
+where only the members at both ends of the sequence
+(called the **front** and the **back** of the queue) can be accessed and removed.
+New members can only be added at the front or at the back.
+
+## Operations
+
+The Deque ADT provides operations to:
+- create a new empty deque
+- add a new member to the front of the deque
+- add a new member to the back of the deque
+- remove the member at the front of the deque
+- remove the member at the back of the deque
+- access the member at the front of the deque without removing it
+- access the member at the back of the deque without removing it
+- compute the size of the deque (number of members).
+
+## Applications
+
+Consider using a deque when you need to simulate a queue where
+- objects jump the queue (join at the front) or
+ leave it from the back after waiting a certain time
+- the direction of the queue changes, like cars on a ferry.
+
+## Implementations
+
+The Deque ADT can be implemented with circular dynamic arrays or doubly-linked lists.
+In both cases, the operations listed above take constant time.
+A doubly-linked list uses much more memory than a static array of the same length,
+but a dynamic array may have wasted capacity and requires resizing.
+`paddles` only provides a doubly-linked list implementation for the moment.
+"""
+
from collections.abc import Sequence
from typing import Any
+__all__ = ["LinkedListDeque"]
+
# A doubly-linked list node is a list [previous, item, next].
# These constants make the code more readable.
PREV = 0
@@ -9,36 +54,50 @@
class LinkedListDeque:
- """Deque implementation using a doubly linked list for storage.
+ """An implementation of the Deque ADT, using a doubly-linked list.
- >>> items = LinkedListDeque("abc")
- >>> print(items)
- LinkedListDeque(['a', 'b', 'c'])
- >>> items.size()
+ Besides the ADT's operations, this class provides two convenience operations:
+ - create a non-empty deque from a given sequence
+ - convert a deque to a string, to see its members listed from front to back.
+
+ >>> from paddles.deque import LinkedListDeque
+ >>> deque = LinkedListDeque("abc") # create a non-empty deque
+ >>> deque.size() # number of members
3
- >>> items.take_front()
+ >>> deque.take_front() # remove and return the front member
'a'
- >>> items.take_back()
+ >>> deque.take_back() # remove and return the back member
'c'
- >>> items.front() == items.back() == 'b'
+ >>> deque.front() == deque.back() == 'b' # return the front and back members
True
- >>> items.add_back("C")
- >>> items.add_front("A")
- >>> print(items)
+ >>> deque.add_back("C") # add a new member at the back
+ >>> deque.add_front("A") # add a new member at the front
+ >>> print(deque) # str(deque) also possible
LinkedListDeque(['A', 'b', 'C'])
"""
- def __init__(self, iterable: Sequence[Any] | None = None) -> None:
- """Initialize this deque with the given items, if any."""
+ def __init__(self, sequence: Sequence[Any] = []) -> None:
+ """Initialize the deque with the members of `sequence`.
+
+ The members are added to the deque in the order they are in `sequence`.
+ To create an empty deque, call `LinkedListDeque()` or `LinkedListDeque([])`.
+
+ Complexity: O(len(`sequence`))
+ """
self._head = None
self._tail = None
self._length = 0
- if iterable:
- for item in iterable:
+ if sequence:
+ for item in sequence:
self.add_back(item)
def __str__(self) -> str:
- """Return a formatted string representation of this deque."""
+ """Return a string representation of the deque.
+
+ The string is 'LinkedListDeque([front member, ..., back member])'.
+
+ Complexity: O(self.size())
+ """
strings = []
current = self._head
while current:
@@ -47,11 +106,41 @@ def __str__(self) -> str:
return f"LinkedListDeque([{', '.join(strings)}])"
def size(self) -> int:
- """Return the number of items in this deque."""
+ """Return how many members the deque has.
+
+ Complexity: O(1)
+ """
return self._length
+ def front(self) -> Any:
+ """Return the item at the front of the deque, without removing it.
+
+ Raise `ValueError` if the deque is empty.
+
+ Complexity: O(1)
+ """
+ if self.size() == 0:
+ msg = "can't access the front of an empty deque"
+ raise ValueError(msg)
+ return self._head[DATA]
+
+ def back(self) -> Any:
+ """Return the item at the back of the deque, without removing it.
+
+ Raise `ValueError` if the deque is empty.
+
+ Complexity: O(1)
+ """
+ if self.size() == 0:
+ msg = "can't access the back of an empty deque"
+ raise ValueError(msg)
+ return self._tail[DATA]
+
def add_front(self, item: Any) -> None:
- """Insert the given item at the front of this deque."""
+ """Put `item` at the front of the deque.
+
+ Complexity: O(1)
+ """
node = [None, item, self._head]
if self.size() == 0:
self._tail = node
@@ -61,7 +150,10 @@ def add_front(self, item: Any) -> None:
self._length += 1
def add_back(self, item: Any) -> None:
- """Insert the given item at the back of this deque."""
+ """Put `item` at the back of the deque.
+
+ Complexity: O(1)
+ """
node = [self._tail, item, None]
if self.size() == 0:
self._head = node
@@ -71,12 +163,14 @@ def add_back(self, item: Any) -> None:
self._length += 1
def take_front(self) -> Any:
- """Remove and return the item at the front of this deque.
+ """Remove and return the item at the front of the deque.
+
+ Raise `ValueError` if the deque is empty.
- Raise ValueError if this deque is empty.
+ Complexity: O(1)
"""
if self.size() == 0:
- msg = "can't take from an empty deque"
+ msg = "can't remove a member from an empty deque"
raise ValueError(msg)
item = self._head[DATA]
self._head = self._head[NEXT]
@@ -88,12 +182,14 @@ def take_front(self) -> Any:
return item
def take_back(self) -> Any:
- """Remove and return the item at the back of this deque.
+ """Remove and return the item at the back of the deque.
+
+ Raise `ValueError` if the deque is empty.
- Raise ValueError if this deque is empty.
+ Complexity: O(1)
"""
if self.size() == 0:
- msg = "can't take from an empty deque"
+ msg = "can't remove a member from an empty deque"
raise ValueError(msg)
item = self._tail[DATA]
self._tail = self._tail[PREV]
@@ -103,23 +199,3 @@ def take_back(self) -> Any:
else:
self._tail[NEXT] = None
return item
-
- def front(self) -> Any:
- """Return the item at the front of this deque without removing it.
-
- Raise ValueError if this deque is empty.
- """
- if self.size() == 0:
- msg = "Deque is empty"
- raise ValueError(msg)
- return self._head[DATA]
-
- def back(self) -> Any:
- """Return the item at the back of this deque without removing it.
-
- Raise ValueError if this deque is empty.
- """
- if self.size() == 0:
- msg = "Deque is empty"
- raise ValueError(msg)
- return self._tail[DATA]
diff --git a/paddles/queue.py b/paddles/queue.py
index 73aa752..d9de481 100644
--- a/paddles/queue.py
+++ b/paddles/queue.py
@@ -1,38 +1,101 @@
+"""This module implements the Queue ADT.
+
+## Intuition
+
+The Queue ADT models a line of objects, e.g. cars waiting to board a ferry.
+Only the object at the front of the line can be accessed and removed.
+The only way to add an object is to put it at the back of the line.
+
+## Definition
+
+A **queue** is a sequence where members are added to one end of the sequence
+(the **back** of the queue) and removed from the other end (the **front** of the queue).
+
+A queue is a **first-in, first-out (FIFO)** sequence:
+the members are removed in the same order they were added.
+
+A queue is a sequence ordered by age (time of addition).
+The oldest member is at the front of the queue, and the youngest member is at the back.
+
+## Operations
+
+The Queue ADT provides operations to:
+- create a new empty queue
+- add a new member, at the back of the existing ones
+- remove the member at the front of the queue
+- access the member at the front of the queue without removing it
+- compute the size of the queue (number of members).
+
+## Applications
+
+Queues are used to implement breadth-first search.
+You should consider using a queue when you need to:
+- simulate a real-life queue, like travellers at passport control or
+ documents in a printer queue
+- process items in the same order they were added, like a to-do list.
+
+## Implementations
+
+The Queue ADT can be implemented with circular dynamic arrays or singly-linked lists.
+In both cases, the operations listed above take constant time.
+A singly-linked list uses much more memory than a static array of the same length,
+but a dynamic array may have wasted capacity and requires resizing.
+`paddles` only provides a singly-linked list implementation for the moment.
+"""
+
from collections.abc import Sequence
from typing import Any
-# A linked list node is a list [item, next].
+__all__ = ["LinkedListQueue"]
+
+# Each linked list node is a list [item, next].
# These constants make the code more readable.
DATA = 0
NEXT = 1
class LinkedListQueue:
- """A queue implemented using a linked list.
+ """An implementation of the Queue ADT, using a singly-linked list.
+
+ Besides the ADT's operations, this class provides two convenience operations:
+ - create a non-empty queue from a given sequence
+ - convert a queue to a string, to see its members listed from front to back.
- >>> q = LinkedListQueue("abc")
- >>> q.size()
+ >>> from paddles.queue import LinkedListQueue
+ >>> q = LinkedListQueue("abc") # create a non-empty queue
+ >>> q.size() # number of members
3
- >>> q.dequeue()
+ >>> q.dequeue() # remove and return the front member
'a'
- >>> q.front()
+ >>> q.front() # return but don't remove the front member
'b'
- >>> q.enqueue("d")
- >>> print(q)
+ >>> q.enqueue("d") # add a new member at the back
+ >>> print(q) # str(q) also possible
LinkedListQueue(['b', 'c', 'd'])
"""
- def __init__(self, iterable: Sequence[Any] | None = None) -> None:
- """Initialize this queue with the given items, if any."""
+ def __init__(self, sequence: Sequence[Any] = []) -> None:
+ """Initialize the queue with the members of `sequence`.
+
+ The members are added to the queue in the order they are in `sequence`.
+ To create an empty queue, call `LinkedListQueue()` or `LinkedListQueue([])`.
+
+ Complexity: O(len(`sequence`))
+ """
self._head = None
self._tail = None
self._length = 0
- if iterable:
- for item in iterable:
+ if sequence:
+ for item in sequence:
self.enqueue(item)
def __str__(self) -> str:
- """Return a formatted string representation of this queue."""
+ """Return a string representation of the queue.
+
+ The string is 'LinkedListQueue([front member, ..., back member])'.
+
+ Complexity: O(self.size())
+ """
strings = []
current = self._head
while current:
@@ -41,11 +104,29 @@ def __str__(self) -> str:
return f"LinkedListQueue([{', '.join(strings)}])"
def size(self) -> int:
- """Return the number of items in this queue."""
+ """Return how many members the queue has.
+
+ Complexity: O(1)
+ """
return self._length
+ def front(self) -> Any:
+ """Return the member at the front of the queue, without removing it.
+
+ Raise `ValueError` if the queue is empty.
+
+ Complexity: O(1)
+ """
+ if self.size() == 0:
+ msg = "can't access the front of an empty queue"
+ raise ValueError(msg)
+ return self._head[DATA]
+
def enqueue(self, item: Any) -> None:
- """Insert the given item at the back of this queue."""
+ """Put `item` at the back of the queue.
+
+ Complexity: O(1)
+ """
node = [item, None]
if self.size() == 0:
self._head = node
@@ -55,17 +136,12 @@ def enqueue(self, item: Any) -> None:
self._tail = node
self._length += 1
- def front(self) -> Any:
- """Return the item at the front of this queue without removing it."""
- if self.size() == 0:
- msg = "can't access front of an empty queue"
- raise ValueError(msg)
- return self._head[DATA]
-
def dequeue(self) -> Any:
- """Remove and return the item at the front of this queue,
+ """Remove and return the item at the front of the queue.
+
+ Raise `ValueError` if the queue is empty.
- or raise ValueError if this queue is empty.
+ Complexity: O(1)
"""
if self.size() == 0:
msg = "can't dequeue from an empty queue"
diff --git a/paddles/stack.py b/paddles/stack.py
index 1e689f9..ff596a7 100644
--- a/paddles/stack.py
+++ b/paddles/stack.py
@@ -1,63 +1,133 @@
+"""This module implements the Stack ADT.
+
+## Intuition
+
+The Stack ADT models a pile of objects, e.g. a pile of storage boxes.
+Only the object at the top of the pile can be accessed and removed.
+The only way to add an object is to put it on top of the existing pile.
+
+## Definition
+
+A **stack** is a sequence where members are removed from and added to
+the same end of the sequence, called the **top** of the stack.
+
+A stack is a **last-in, first-out (LIFO)** sequence:
+the next member to be removed is the one most recently added.
+
+A stack is a sequence ordered by age (time of addition).
+The oldest member is at the bottom of the stack, and the youngest member is at the top.
+
+## Operations
+
+The Stack ADT provides operations to:
+- create a new empty stack
+- add a new member, on top of the existing ones
+- remove the member at the top of the stack
+- access the member at the top of the stack without removing it
+- compute the size of the stack (number of members).
+
+## Applications
+
+Stacks are used to implement function calls and depth-first search.
+You should consider using a stack when you need to:
+- simulate the handling of a pile of objects, like loading and unloading ship containers
+- process nested structures, like brackets (e.g. `print([1, {2, 3}])`) or
+ HTML tags (e.g. `text
`)
+- process items in the reverse order they were added, like undo operations
+ (the next command to be undone is the most recently executed one).
+
+## Implementations
+
+The Stack ADT can be implemented with dynamic arrays or singly-linked lists.
+In both cases, the operations listed above take constant time.
+A singly-linked list uses much more memory than a static array of the same length,
+but a dynamic array may have wasted capacity and requires resizing.
+"""
+
from collections.abc import Sequence
from typing import Any
+__all__ = ["DynamicArrayStack", "LinkedListStack"]
+
class DynamicArrayStack:
- """A stack implementation using Python lists.
+ """An implementation of the Stack ADT, using Python lists.
+
+ Besides the ADT's operations, this class provides two convenience operations:
+ - create a non-empty stack from a given sequence
+ - convert a stack to a string, to see its members listed from bottom to top.
- >>> stack = DynamicArrayStack("abc")
- >>> stack.size()
+ >>> from paddles.stack import DynamicArrayStack
+ >>> stack = DynamicArrayStack("abc") # create a non-empty stack
+ >>> stack.size() # number of members
3
- >>> stack.pop()
+ >>> stack.pop() # remove and return the top member
'c'
- >>> stack.peek()
+ >>> stack.peek() # return but don't remove the top member
'b'
- >>> stack.push("C")
- >>> print(stack)
+ >>> stack.push("C") # add a new member on top
+ >>> print(stack) # str(stack) also possible
DynamicArrayStack(['a', 'b', 'C'])
"""
- def __init__(self, iterable: Sequence[Any] | None = None) -> None:
- """Initialize this stack with the given items, if any."""
- if iterable:
- self._members = list(iterable)
- else:
- self._members = []
+ def __init__(self, sequence: Sequence[Any] = []) -> None:
+ """Initialize the stack with the members of `sequence`.
+
+ The members are added to the stack in the order they are in `sequence`.
+ To create an empty stack, call `DynamicArrayStack()` or `DynamicArrayStack([])`.
+
+ Complexity: O(len(`sequence`))
+ """
+ self._members = []
+ for item in sequence:
+ self.push(item)
def __str__(self) -> str:
- """Return a string representation of this stack.
+ """Return a string representation of the stack.
The string is 'DynamicArrayStack([bottom member, ..., top member])'.
+
+ Complexity: O(self.size())
"""
return f"DynamicArrayStack({self._members})"
def size(self) -> int:
- """Return how many members this stack has."""
+ """Return how many members the stack has.
+
+ Complexity: O(1)
+ """
return len(self._members)
- def push(self, item: Any) -> None:
- """Add the given item to the top of this stack."""
- self._members.append(item)
+ def peek(self) -> Any:
+ """Return the member at the top of the stack, without removing it.
- def pop(self) -> Any:
- """Remove and return the top item of this stack.
+ Raise `ValueError` if the stack is empty.
- Raise ValueError if this stack is empty.
+ Complexity: O(1)
"""
if self.size() == 0:
- msg = "can't pop a member from an empty stack"
+ msg = "can't peek into an empty stack"
raise ValueError(msg)
- return self._members.pop()
+ return self._members[-1]
- def peek(self) -> Any:
- """Return the top item of this stack.
+ def push(self, item: Any) -> None:
+ """Put `item` on top of the stack.
- Raise ValueError if this stack is empty.
+ Complexity: O(1)
+ """
+ self._members.append(item)
+
+ def pop(self) -> Any:
+ """Remove and return the member at the top of the stack.
+
+ Raise `ValueError` if the stack is empty.
+
+ Complexity: O(1)
"""
if self.size() == 0:
- msg = "can't peek into an empty stack"
+ msg = "can't pop a member from an empty stack"
raise ValueError(msg)
- return self._members[-1]
+ return self._members.pop()
# Each linked list node is a tuple (data, next).
@@ -67,32 +137,44 @@ def peek(self) -> Any:
class LinkedListStack:
- """A stack implementation using singly-linked lists.
+ """An implementation of the Stack ADT, using singly-linked lists.
- >>> stack = LinkedListStack("abc")
- >>> stack.size()
+ Besides the ADT's operations, this class provides two convenience operations:
+ - create a non-empty stack from a given sequence
+ - convert a stack to a string, to see its members listed from bottom to top.
+
+ >>> from paddles.stack import LinkedListStack
+ >>> stack = LinkedListStack("abc") # create a non-empty stack
+ >>> stack.size() # number of members
3
- >>> stack.pop()
+ >>> stack.pop() # remove and return the top member
'c'
- >>> stack.peek()
+ >>> stack.peek() # return but don't remove the top member
'b'
- >>> stack.push("C")
- >>> print(stack)
+ >>> stack.push("C") # add a new member on top
+ >>> print(stack) # str(stack) also possible
LinkedListStack(['a', 'b', 'C'])
"""
- def __init__(self, iterable: Sequence[Any] | None = None) -> None:
- """Initialize this stack with the given items, if any."""
+ def __init__(self, sequence: Sequence[Any] = []) -> None:
+ """Initialize the stack with the members of `sequence`.
+
+ The members are added to the stack in the order they are in `sequence`.
+ To create an empty stack, call `LinkedListStack()` or `LinkedListStack([])`.
+
+ Complexity: O(len(`sequence`))
+ """
self._head = None
self._length = 0
- if iterable:
- for item in iterable:
- self.push(item)
+ for item in sequence:
+ self.push(item)
def __str__(self) -> str:
- """Return a string representation of this stack.
+ """Return a string representation of the stack.
The string is 'LinkedListStack([bottom member, ..., top member])'.
+
+ Complexity: O(self.size())
"""
strings = []
current = self._head
@@ -102,18 +184,26 @@ def __str__(self) -> str:
return "LinkedListStack([" + ", ".join(reversed(strings)) + "])"
def size(self) -> int:
- """Return how many members this stack has."""
+ """Return how many members the stack has.
+
+ Complexity: O(1)
+ """
return self._length
def push(self, item: Any) -> None:
- """Add the given item to the top of this stack."""
+ """Put `item` on top of the stack.
+
+ Complexity: O(1)
+ """
self._head = (item, self._head)
self._length += 1
def pop(self) -> Any:
- """Remove and return the item on the top of this stack.
+ """Remove and return the member at the top of the stack.
+
+ Raise `ValueError` if the stack is empty.
- Raise ValueError if this stack is empty.
+ Complexity: O(1)
"""
if self.size() == 0:
msg = "can't pop a member from an empty stack"
@@ -124,9 +214,11 @@ def pop(self) -> Any:
return item
def peek(self) -> Any:
- """Return the item on the top of this stack.
+ """Return the member at the top of the stack.
+
+ Raise `ValueError` if the stack is empty.
- Raise ValueError if this stack is empty.
+ Complexity: O(1)
"""
if self.size() == 0:
msg = "can't peek into an empty stack"
diff --git a/poetry.lock b/poetry.lock
index e01ff81..d532560 100644
--- a/poetry.lock
+++ b/poetry.lock
@@ -403,6 +403,25 @@ files = [
{file = "packaging-23.2.tar.gz", hash = "sha256:048fb0e9405036518eaaf48a55953c750c11e1a1b68e0dd1a9d62ed0c092cfc5"},
]
+[[package]]
+name = "pdoc"
+version = "14.3.0"
+description = "API Documentation for Python Projects"
+optional = false
+python-versions = ">=3.8"
+files = [
+ {file = "pdoc-14.3.0-py3-none-any.whl", hash = "sha256:9a8f9a48bda5a99c249367c2b99779dbdd9f4a56f905068c9c2d6868dbae6882"},
+ {file = "pdoc-14.3.0.tar.gz", hash = "sha256:40bf8f092fcd91560d5e6cebb7c21b65df699f90a468c8ea316235c3368d5449"},
+]
+
+[package.dependencies]
+Jinja2 = ">=2.11.0"
+MarkupSafe = "*"
+pygments = ">=2.12.0"
+
+[package.extras]
+dev = ["hypothesis", "mypy", "pdoc-pyo3-sample-library (==1.0.11)", "pygments (>=2.14.0)", "pytest", "pytest-cov", "pytest-timeout", "ruff", "tox", "types-pygments"]
+
[[package]]
name = "platformdirs"
version = "4.1.0"
@@ -481,6 +500,21 @@ dev = ["black", "chardet"]
release = ["zest.releaser[recommended]"]
tests = ["black", "chardet", "tox"]
+[[package]]
+name = "pygments"
+version = "2.17.2"
+description = "Pygments is a syntax highlighting package written in Python."
+optional = false
+python-versions = ">=3.7"
+files = [
+ {file = "pygments-2.17.2-py3-none-any.whl", hash = "sha256:b27c2826c47d0f3219f29554824c30c5e8945175d888647acd804ddd04af846c"},
+ {file = "pygments-2.17.2.tar.gz", hash = "sha256:da46cec9fd2de5be3a8a784f434e4c4ab670b4ff54d605c4c2717e9d49c4c367"},
+]
+
+[package.extras]
+plugins = ["importlib-metadata"]
+windows-terminal = ["colorama (>=0.4.6)"]
+
[[package]]
name = "pyparsing"
version = "3.1.1"
@@ -756,4 +790,4 @@ test = ["covdefaults (>=2.3)", "coverage (>=7.2.7)", "coverage-enable-subprocess
[metadata]
lock-version = "2.0"
python-versions = "^3.10"
-content-hash = "1f184fd249a04f522982bd5c412fe84090a94d1dbc36a2198850980312bc4e5a"
+content-hash = "a87613c91c03d734e344dcd5c134b369af11d777c8134129973247daf1bfbe04"
diff --git a/pyproject.toml b/pyproject.toml
index 0d5cf7c..8d859f1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -14,6 +14,7 @@ pytest-cov = "^4.1.0"
pre-commit = "^3.6.0"
ruff = "^0.1.9"
pytype = "^2023.12.18"
+pdoc = "^14.3.0"
[build-system]
requires = ["poetry-core"]
@@ -27,13 +28,15 @@ target-version = "py310"
[tool.ruff.lint]
select = ["ALL"]
-ignore = [
- "ANN101", # don't require type annotations for `self`
- "ANN401", # don't flag annotations with `Any`
- "D", # don't flag missing documentation yet
- "ISC001", "COM812", # ignore rules that conflict with formatter
+ignore = [ # ignore these rules:
+ "ANN101", # provide the type of `self`
+ "ANN401", # don't use `Any`
+ "ISC001", "COM812", # these rules may conflict with the formatter
]
+[tool.ruff.lint.pydocstyle]
+convention = "pep257" # this project's docstrings follow PEP 257
+
[tool.ruff.lint.per-file-ignores]
-# don't flag assertions in test code: they're used by pytest
-"test_*.py" = ["S101"]
+# in test code, don't flag assertions nor missing package docstrings
+"tests/*py" = ["S101", "D104"]
diff --git a/tests/test_deque.py b/tests/test_deque.py
index d094856..3ff6871 100644
--- a/tests/test_deque.py
+++ b/tests/test_deque.py
@@ -13,13 +13,13 @@
def check_is_empty(deque: DequeADT) -> None:
"""Test that the deque is empty."""
assert deque.size() == 0
- with pytest.raises(ValueError, match="Deque is empty"):
+ with pytest.raises(ValueError, match="can't access the front of an empty deque"):
deque.front()
- with pytest.raises(ValueError, match="Deque is empty"):
+ with pytest.raises(ValueError, match="can't access the back of an empty deque"):
deque.back()
- with pytest.raises(ValueError, match="can't take from an empty deque"):
+ with pytest.raises(ValueError, match="can't remove a member from an empty deque"):
deque.take_front()
- with pytest.raises(ValueError, match="can't take from an empty deque"):
+ with pytest.raises(ValueError, match="can't remove a member from an empty deque"):
deque.take_back()
assert str(deque) == f"{deque.__class__.__name__}([])"
diff --git a/tests/test_queue.py b/tests/test_queue.py
index 41ba0ae..6ed6be1 100644
--- a/tests/test_queue.py
+++ b/tests/test_queue.py
@@ -14,7 +14,7 @@
def check_is_empty(queue: QueueADT) -> None:
"""Test that the queue is empty."""
assert queue.size() == 0
- with pytest.raises(ValueError, match="can't access front of an empty queue"):
+ with pytest.raises(ValueError, match="can't access the front of an empty queue"):
queue.front()
with pytest.raises(ValueError, match="can't dequeue from an empty queue"):
queue.dequeue()