pycommons: Common Utility Functions for Python Projects.

make build pypi version pypi downloads coverage report

1. Introduction

In this project, we combine several utilities and functions that are used in our other projects.

These functions have in common that they are fail-fast. They usually check the types of all of their inputs and raise exceptions immediately if something looks dodgy. There is no garbage-in/garbage-out: Our functions raise descriptive errors as soon as they detect something strange.

2. Installation

In order to use this package, you need to first install it using pip or some other tool that can install packages from PyPi. You can install the newest version of this library from PyPi using pip by doing

pip install pycommons

This will install the latest official release of our package as well as all dependencies. If you want to install the latest source code version from GitHub (which may not yet be officially released), you can do

pip install git+https://github.com/thomasWeise/pycommons.git

If you want to install the latest source code version from GitHub (which may not yet be officially released) and you have set up a private/public key for GitHub, you can also do:

git clone ssh://git@github.com/thomasWeise/pycommons
pip install pycommons

This may sometimes work better if you are having trouble reaching GitHub via https or http.

You can also clone the repository and then run a make build, which will automatically install all dependencies, run all the tests, and then install the package on your system, too. This will work only on Linux, though. If this build completes successful, you can be sure that pycommons will work properly on your machine.

All dependencies for using and running pycommons are listed at here.

3. Examples

3.1. Data Structures

from pycommons.ds.cache import str_is_new

cache = str_is_new()
print(cache("1"))
print(cache("2"))
print(cache("1"))
print(cache("3"))
print(cache("2"))

prints True, True, False, True, and False.

from pycommons.ds.immutable_map import immutable_mapping

imap = immutable_mapping({1: 2, 3: 4})
try:
    imap[1] = 3
except TypeError as te:
    print(te)

print(imap[1])

prints 'mappingproxy' object does not support item assignment and 2.

4. License

pycommons is a library with utilities for Python projects.

Copyright (C) 2024 Thomas Weise (汤卫思教授)

Dr. Thomas Weise (see Contact) holds the copyright of this package.

pycommons is provided to the public as open source software under the GNU GENERAL PUBLIC LICENSE, Version 3, 29 June 2007. Terms for other licenses, e.g., for specific industrial applications, can be negotiated with Dr. Thomas Weise (who can be reached via the contact information below).

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see https://www.gnu.org/licenses/.

Please visit the contributions guidelines for pycommons if you would like to contribute to our package. If you have any concerns regarding security, please visit our security policy.

5. Contact

If you have any questions or suggestions, please contact Prof. Dr. Thomas Weise (汤卫思教授) of the Institute of Applied Optimization (应用优化研究所, IAO) of the School of Artificial Intelligence and Big Data (人工智能与大数据学院) at Hefei University (合肥大学) in Hefei, Anhui, China (中国安徽省合肥市) via email to tweise@hfuu.edu.cn with CC to tweise@ustc.edu.cn.

6. Modules and Code