Overloaded Iterables

Overloaded versions of the built-in python classes: <list> and <set>, to include some extra functionalities as an experiment.

An experimental Python package to extend the methods found in Python's built-in list and set classes to add some extra functionality that I, personally find useful in my day-to-day implementations and was too lazy to keep writing/copy-pasting again and again.

Python Package Index

Installation

python -m pip install overloaded-iterables

Classes

The current iteration contains the following classes

1. OverloadedList

A non-datatype constrained, single-dimensional collection of values.
Inherits solely from Python's built-in <list> class.

from overloaded_iterables.classes import OverloadedList

obj = OverloadedList(*args)

2. Queue

A non-datatype constrained, single-dimensional collection of values that follows the first-in-first-out (FiFo) principle for insertions and deletion i.e, insertions will be made to the end of the sequence while deletions will be made to the beginning of the sequence.
Inherits solely from the <OverloadedList> class.

from overloaded_iterables.classes import Queue

obj = Queue(*args)

3. Stack

A non-datatype constrained, single-dimensional collection of values that follows the first-in-last-out (FiLo) principle for insertions and deletion i.e, insertions and deletions, both will be made to the end of the sequence.
Inherits solely from the <OverloadedList> class.

from overloaded_iterables.classes import Stack

obj = Stack(*args)

4. OverloadedSet

A non-datatype constrained, single-dimensional collection of unique values.
Inherits solely from Python's built-in <set> class.

    from overloaded_iterables.classes import OverloadedSet

    obj = OverloadedSet(*args)

Functions and Methods

The functions, methods and properties are categorised into two segments: for the base classes (OverloadedList and OverloadedSet) and for the inheriting classes (Queue and Stack)

OverloadedList and OverloadedSet

The following are the functions, methods and properties belonging to the base classes.

OverloadedList being a daughter of the <list> class, inherits all of its associated methods and properties as well, such as append(), extend(), count(), et cetera.

OverloadedSet being a daughter of the <set> class, inherits all of its associated methods and properties as well, such as add(), clear(), difference(), et cetera.

<class>.mean()
- Find the mean of the values in the given iterable class object.
- Arguments: self
- Returns: float (64-bit)
- Example:
```
    _mean: float = obj.mean()
```
<class>.sum()
- Claculate the sum of all the elements in the given iterable class object.
- Arguments: self
- Returns: float (64-bit)
- Example:
```
    _sum: float = obj.sum()
```
<class>.prod()
- Calculate the product of all the elements in the given iterable class object.
- Arguments: self
- Returns: float (64-bit)
- Example:
```
    _product: float = obj.prod()
```
<class>.sort()
- Sorts the contents of the given iterable class object via the Timsort sorting algorithm.
- Arguments: self, key: None | default: None, reverse: bool | default: False
- Returns object: <list>
- Example:
```
    sorted_seq: list = obj.sort()
```

<class>.raise_to()

Raises each element in the iterable class object to the given power.
Arguments: self, power: float (64-bit) | default: 1.0
Returns object: <class>

Example:

    import numpy as np
    from secrets import choice

    ## Taking the power variable, 'z' to be a random integer between -10 and +10
    z:float = choice([i for i in np.arange(-10, 10, 0.5)])
    _raised_sequence: type(obj) = obj.raise_to(power=z)

<class>.rms()
- Finds the Root-Mean-Square (RMS) of the values in the current iterable class object.
- Arguments: self, power: float | default: 2, root: int | default: 2
- Returns: float (64-bit)
- Example:
```
    _rms: float = obj.rms()
```
<class>.median()
- Finds the median of the contents of the given iterable class object.
- Arguments: self
- Returns: float (64-bit)
- Example:
```
    _median:float = obj.median()
```
<class>.hist() (OverloadedList only)
- Plots the histogram of the frequency distribution of the elements in the OverloadedList.
- Arguments: self, bins: int | default: 10, title: str | default: 'Histogram', x_label: str | default: 'Values --->', y_label: str | default: 'Frequencies --->', save_dir: str | default: None, file_name: str | default: None, histtype: str | default: 'step', align: str | default: 'mid', orientation: str | default: 'vertical', log_scale: bool | default: False, show: bool | default: False
- Process:
  - Shows the generated figure if show is set to True
  - Saves the generated figure if save_dir is provided.
- Returns: bool
- Example:
```
    fig_check:bool = obj.hist(show=True, save_dir='figures', file_name='some-figure')
```
<class>.plot() (OverloadedList only)
- Plots the lineplot of the frequency distribution of the elements in the OverloadedList.
- Arguments: self, title: str | default: 'Line Plot', x_label: str | default: 'Values --->', y_label: str | default: 'Frequencies --->', save_dir: str | default: None, file_name: str | default: None, color: str | default: '#000000', linewidth: float | default: 1, marker: str | default: ',', markerfacecolor: str | default: '#252525', marker_size: float | default: 1.0, show: bool | default: False
- Process:
  - Shows the generated figure if show is set to True
  - Saves the generated figure if save_dir is provided.
- Returns: bool
- Example:
```
    fig_check:bool = obj.plot(show=True, save_dir='figures', file_name='some-figure')
```
<class>.scatter() (OverloadedList only)
- Plots the scatterplot of the frequency distribution of the elements in the OverloadedList.
- Arguments: self, title: str | default: 'Scatter Plot', x_label: str | default: 'Values --->', y_label: str | default: 'Frequencies --->', save_dir: str | default: None, file_name: str | default: None, size: List[float] | default: [1.25], color: str | default: '#000000', marker: str | default: ',', line_width: float | default: 2, show: bool | default: False
- Process:
  - Shows the generated figure if show is set to True
  - Saves the generated figure if save_dir is provided.
- Returns: bool
- Example:
```
    fig_check:bool = obj.scatter(show=True, save_dir='figures', file_name='some-figure')
```
<class>.len (property)
- Finds and returns the length of the current iterable class object as a property.
- Arguments: self
- Returns: int
- Example:
```
    _l: int = obj.len
```
<class>.frequencies (property) (OverloadedList only)
- Finds the frequencies of all elements of the given OverloadedList class and returns a list of unique values with their discovered frequencies.
- Arguments: self
- Returns: OverloadedList, OverloadedList
- Example:
```
    values: Overloadedlist, frequencies: OverloadedList = obj.frequencies
```

Queue and Stack

The following are the functions, methods and properties belonging to the inheriting (daughter) classes.

Queue and Stack being daughters of the OverloadedList class, inherit all of its associated methods and properties as well, such as mean(), rms(), frequencies, et cetera.

<class>.insert()

Inserts value towards the end of the object.
Arguments: self, value: any
Returns: None (is an in-place method)

Example:

    queue = Queue(*args)
    stack = Stavk(*args)
    queue.insert(value=value)
    stack.insert(value=value)

<class>.pop()
- Deletes num elements from the beginning of the object in case of Queue and from the end of the object in case of Stack.
- Arguments: self, num: int | default: 1
- Returns: None (is an in-place method)
- Example:
```
    queue = Queue(*args)
    stack = Stack(*args)
    queue.pop(num=num)
    stack.pop(num=num)
```

Development Setup

git clone https://<personal-access-token>@github.com/Arkiralor/overloaded_iterables.git
cd overloaded_aiterables
python -m venv env
source env/bin/activate
1. source env/Scripts/activate for Windows.
chmod +x scripts/*
sh scripts/install.sh to install all dependencies.
1. sh scripts/uninstall.sh to uninstall all dependencies (can be very useful if you forgot to activate the virtualEnvironment before running install.sh).
sh scripts/generate_coverage_report && sh scripts/run_tests.sh to make sure everything is working as intended.

Contribution

If you choose to contribute to this package by addressing any of the issues or tickets listed, kindly follow the following workflow.

Assign yourself or ask an administrator to assign yourself to the issue.
Clone/fork the codebase and setup the development environment as shown above.
Checkout to your own branch, which should ideally be named what the ticket number is in a url-safe format i.e, if the ticket name is WEB_003, then the branch name will be web-003.
git push --set-upstream origin <branchName> to pre-create the necessary branch on github.
Make the required changes to the correct files in the src directory.
Add any testCases required to the correct module/file/class in the tests directory.
sh scripts/run_tests.sh to make sure no breaking changes were made.
1. MAKE SURE ALL TESTS PASS BEFORE PROCEEDING TO THE NEXT STEP(S)
Add and commit your changes to your branch with a relevant commit message.
git merge origin/master to pull from the master branch to your branch.
sh scripts/run_tests.sh again to make sure nothing was broken by the merge.
1. MAKE SURE ALL TESTS PASS BEFORE PROCEEDING TO THE NEXT STEP(S)
git push to push the changes to the remote branch.
Create a Pull Request from your remote branch to master.
1. If any code changes were requested, execute them as requested and restart from step #6.

arkiralor / overloaded_iterables Goto Github PK