zaowr-polsl-kisiel 0.0.3

A simple Python package used by me and a friend at the university in the course 'Advanced Image, Video and Motion Analysis'

ZAOWR Package

This is a ZAOWR (Zaawansowana Analiza Obrazu, Wideo i Ruchu, eng. Advanced Image, Video, and Motion Analysis) Python package used by me and a friend at the university.

PyPI link to the package

• MAIN PyPI


• TEST PyPI

Installing the package using pip

1. PyPI MAIN
   
   • Linux
     

     python3 -m pip install --upgrade zaowr-polsl-kisiel
     

   
   
   • Windows
     

     py -m pip install --upgrade zaowr-polsl-kisiel
     



2. TestPyPI
   
   • Linux
     

     python3 -m pip install --index-url https://test.pypi.org/simple/ --upgrade zaowr-polsl-kisiel
     

   
   
   • Windows
     

     py -m pip install --index-url https://test.pypi.org/simple/ --upgrade zaowr-polsl-kisiel
     

Creating virtual environment for the package

[!NOTE]

Complete instructions on managing Python virtual environments

can be found here.

1. Create project directory (where you create your files and where the venv will be created)
   

   python -m venv ENV_NAME
   




[!NOTE]

ENV_NAME is the name of your venv, so you can change it however you like



2. Activate the venv (while in the project directory)
   

   source ENV_NAME/bin/activate
   

   or

   . ENV_NAME/bin/activate
   



3. Install the package from PyPI
   

   python3 -m pip install --upgrade zaowr-polsl-kisiel
   



4. Deactivate the currently active venv
   

   deactivate
   



5. To reactivate the venv, navigate to the path where you created the venv and source it again (command shown above in section number 2)

Building package - DEV Tutorial based on official DOCS

1. Install pip
   

   python3 -m pip install --upgrade pip
   



2. Prepare files and directories
   

   directory_used_for_package/
   ├── LICENSE
   ├── pyproject.toml
   ├── README.md
   ├── src/
   │   └── name_of_the_package/
   │       ├── __init__.py
   │       └── example.py
   └── tests/
   



3. Choose build backend (I chose setuptools)
   

   python3 -m pip install --upgrade setuptools
   



4. Prepare pyproject.toml file (this package's configuration as an example)
   

   [build-system]
   requires = ["setuptools>=61.0"]
   build-backend = "setuptools.build_meta"
   
   [project]
   name = "zaowr_polsl_kisiel"
   dynamic = ["version"]
   authors = [
   { name="Maksymilian Kisiel", email="[e-mail]" },
   ]
   description = "A simple Python package used by me and a friend at the university in the course 'Advanced Image, Video and Motion Analysis'"
   readme = "README.md"
   requires-python = ">=3.8"
   classifiers = [
       "Programming Language :: Python :: 3",
       "License :: OSI Approved :: MIT License",
       "Operating System :: OS Independent",
   ]
   keywords = ["polsl", "zaowr", "2024", "IGT", "ZAOWR"]
   
   [tool.setuptools.dynamic]
   dependencies = {file = "requirements.txt"}
   
   [project.urls]
   Homepage = "https://github.com/revalew/zaowr-py-package"
   Issues = "https://github.com/revalew/zaowr-py-package/issues"
   




[!NOTE]

requirements.txt file listed as "dependencies" was created using pip freeze > requirements.txt command

which was executed in active python venv prepared for this uni course.

Check my tutorial on managing venvs here.



5. Prepare README.md file (customize this as you’d like)


6. Prepare LICENSE file (MIT license shown below, more licenses can be found here)
   

   Copyright (c) 2018 The Python Packaging Authority
   
   Permission is hereby granted, free of charge, to any person obtaining a copy
   of this software and associated documentation files (the "Software"), to deal
   in the Software without restriction, including without limitation the rights
   to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
   copies of the Software, and to permit persons to whom the Software is
   furnished to do so, subject to the following conditions:
   
   The above copyright notice and this permission notice shall be included in all
   copies or substantial portions of the Software.
   
   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
   FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
   AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
   OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
   SOFTWARE.
   



7. Instal the build tool (if you encounter errors see official tutorial)
   

   python3 -m pip install --upgrade build
   



8. Navigate to the folder where the pyproject.toml file is located


9. Generate distribution archives
   

   python3 -m build
   



10. Verify that the build was successful
    

    In the package there should now be dist/ directory. The tar.gz file is a source distribution whereas the .whl file is a built distribution. Newer pip versions preferentially install built distributions, but will fall back to source distributions if needed. You should always upload a source distribution and provide built distributions for the platforms your project is compatible with.

    
    

    dist/
    ├── zaowr_polsl_kisiel-0.0.0-py3-none-any.whl
    └── zaowr_polsl_kisiel-0.0.0.tar.gz
    



11. Register the account in TestPyPI or PyPI (just follow the given instructions)


12. Generate API token for TestPyPI or PyPI (just follow the given instructions, I added the credentials to $HOME/.pypirc using [pypi] and [testpypi] headers)


13. Instal twine to upload the package
    

    python3 -m pip install --upgrade twine
    



14. Upload the package
    
    • If you didn't add the credentials to $HOME/.pypirc, you will be prompted for username and password. Use __token__ for username and pypi-* (your API token) for password
    
    
    • PyPI
      

      python3 -m twine upload dist/*
      

    
    
    • TestPyPI
      

      python3 -m twine upload --repository testpypi dist/*
      



15. After the upload succeeded, the package should be vievable on PyPI or TestPyPI


16. Installing the package
    
    • PyPI
      

      python3 -m pip install --upgrade zaowr-polsl-kisiel
      

    
    
    • TestPyPI
      

      python3 -m pip install --upgrade --index-url https://test.pypi.org/simple/ --no-deps zaowr-polsl-kisiel
      

    
    

[!NOTE]

Here we additionally use --no-deps flag.

Since TestPyPI doesn’t have the same packages as the live PyPI, it’s possible that attempting to install dependencies may fail or install something unexpected.



17. Test the installation
    
    • Launch python
      

      python3
      

    
    
    • Import the package
      

      >>> from zaowr_polsl_kisiel.read_calibration import read_calibration
      >>> read_calibration()
      

Sources

This package has been prepared following this tutorial.