Merge pull request #337 from roboflow/develop

`supervision-0.14.0` release

.gitattributes

@@ -1 +1 @@
-*.ipynb linguist-vendored
+*.ipynb linguist-vendored

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -62,4 +62,4 @@ body:
  description: >
  (Optional) We encourage you to submit a [Pull Request](https://github.com/roboflow/supervision/pulls) (PR) to help improve Supervision for everyone, especially if you have a good understanding of how to implement a fix or feature.
  options:
- - label: Yes I'd like to help by submitting a PR!
+ - label: Yes I'd like to help by submitting a PR!

.github/ISSUE_TEMPLATE/feature-request.yml

@@ -46,4 +46,4 @@ body:
  description: >
  (Optional) We encourage you to submit a [Pull Request](https://github.com/roboflow/supervision/pulls) (PR) to help improve Supervision for everyone, especially if you have a good understanding of how to implement a fix or feature.
  options:
- - label: Yes I'd like to help by submitting a PR!
+ - label: Yes I'd like to help by submitting a PR!

.github/ISSUE_TEMPLATE/question.yml

@@ -30,4 +30,4 @@ body:
  - type: textarea
  attributes:
  label: Additional
- description: Anything else you would like to share?
+ description: Anything else you would like to share?

.github/workflows/publish-test.yml

@@ -0,0 +1,41 @@
+name: Supervision Test Releases to PyPi
+on:
+ push:
+ tags:
+ - '[0-9]+.[0-9]+[0-9]+.[0-9]+a[0-9]'
+ - '[0-9]+.[0-9]+[0-9]+.[0-9]+b[0-9]'
+ - '[0-9]+.[0-9]+[0-9]+.[0-9]+rc[0-9]'
+
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
+
+jobs:
+ build-n-publish:
+ name: Build and publish to PyPI
+ runs-on: ubuntu-latest
+
+ steps:
+ - name: Checkout source
+ uses: actions/checkout@v3
+
+ - name: 🐍 Set up Python 3.8 environment for build
+ uses: actions/setup-python@v4
+ with:
+ python-version: "3.8"
+
+ - name: 🏗️ Build source and wheel distributions
+ run: |
+ python -m pip install --upgrade build twine
+ python -m build
+ twine check --strict dist/*
+ - name: 🚀 Publish distribution to PyPI
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ user: ${{ secrets.PYPI_USERNAME }}
+ password: ${{ secrets.PYPI_PASSWORD }}
+ - name: 🚀 Publish to Test-PyPi
+ uses: pypa/gh-action-pypi-publish@release/v1
+ with:
+ repository-url: https://test.pypi.org/legacy/
+ user: ${{ secrets.PYPI_TEST_USERNAME }}
+ password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/publish.yml

@@ -1,8 +1,13 @@
-name: Publish WorkFlow
-
+name: Supervision Releases to PyPi
 on:
- release:
- types: [created]
+ push:
+ tags:
+ - '[0-9]+.[0-9]+[0-9]+.[0-9]'
+ - '[0-9]+.[0-9]+[0-9]+.[0-9]'
+ - '[0-9]+.[0-9]+[0-9]+.[0-9]'
+
+ # Allows you to run this workflow manually from the Actions tab
+ workflow_dispatch:
 
 jobs:
  build:
@@ -19,15 +24,6 @@ jobs:
  uses: actions/setup-python@v4
  with:
  python-version: ${{ matrix.python-version }}
- - name: 🦾 Install dependencies
- run: |
- python -m pip install --upgrade virtualenv
- python -m pip install --upgrade pip
- virtualenv venv
- source venv/bin/activate
- python -m pip install --upgrade pip
- python -m pip install --upgrade poetry
- poetry install
 
  - name: 🏗️ Build source and wheel distributions
  run: |
@@ -43,5 +39,5 @@ jobs:
  uses: pypa/gh-action-pypi-publish@release/v1
  with:
  repository-url: https://test.pypi.org/legacy/
- user: ${{ secrets.PYPI_USERNAME }}
+ user: ${{ secrets.PYPI_TEST_USERNAME }}
  password: ${{ secrets.PYPI_TEST_PASSWORD }}

.github/workflows/test.yml

@@ -25,8 +25,5 @@ jobs:
  pip install isort
  pip install flake8
  pip install "black==22.3.0"
- - name: 🧹 Lint with flake8
- run: |
- make check_code_quality
  - name: 🧪 Test
- run: "python -m pytest ./test"
+ run: "python -m pytest ./test"

.github/workflows/welcome.yml

@@ -15,4 +15,4 @@ jobs:
  with:
  repo-token: ${{ secrets.GITHUB_TOKEN }}
  issue-message: "Hello there, thank you for opening an Issue ! 🙏🏻 The team was notified and they will get back to you asap."
- pr-message: "Hello there, thank you for opening an PR ! 🙏🏻 The team was notified and they will get back to you asap."
+ pr-message: "Hello there, thank you for opening an PR ! 🙏🏻 The team was notified and they will get back to you asap."

.gitignore

@@ -54,6 +54,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
 
 # Translations
 *.mo

.pre-commit-config.yaml

@@ -0,0 +1,80 @@
+
+ci:
+ autofix_prs: true
+ autoupdate_schedule: weekly
+ autofix_commit_msg: "fix(pre_commit): 🎨 auto format pre-commit hooks"
+ autoupdate_commit_msg: "chore(pre_commit): ⬆ pre_commit autoupdate"
+
+repos:
+ - repo: https://github.com/pre-commit/pre-commit-hooks
+ rev: v4.4.0
+ hooks:
+ - id: end-of-file-fixer
+ - id: trailing-whitespace
+ - id: check-yaml
+ - id: check-docstring-first
+ - id: check-executables-have-shebangs
+ - id: check-toml
+ - id: check-case-conflict
+ - id: check-added-large-files
+ args: ['--maxkb=2048']
+ exclude: ^logo/
+ - id: detect-private-key
+ - id: forbid-new-submodules
+ - id: pretty-format-json
+ args: ['--autofix', '--no-sort-keys', '--indent=4']
+ - id: end-of-file-fixer
+ - id: mixed-line-ending
+
+ # - repo: https://github.com/asottile/pyupgrade
+ # rev: v3.9.0
+ # hooks:
+ # - id: pyupgrade
+ # name: Upgrade code
+ # args: [--py38-plus]
+
+ - repo: https://github.com/PyCQA/isort
+ rev: 5.12.0
+ hooks:
+ - id: isort
+ name: Sort imports
+
+ - repo: https://github.com/PyCQA/flake8
+ rev: 6.1.0
+ hooks:
+ - id: flake8
+ name: Flake8 Checks
+ entry: flake8
+ additional_dependencies: [Flake8-pyproject]
+
+
+ - repo: https://github.com/PyCQA/bandit
+ rev: '1.7.5'
+ hooks:
+ - id: bandit
+ args: ["-c", "pyproject.toml"]
+ additional_dependencies: ["bandit[toml]"]
+
+ - repo: https://github.com/pycqa/isort
+ rev: 5.12.0
+ hooks:
+ - id: isort
+ name: isort (python)
+ - id: isort
+ name: isort (cython)
+ types: [cython]
+ - id: isort
+ name: isort (pyi)
+ types: [pyi]
+
+
+ - repo: https://github.com/psf/black
+ rev: 23.7.0
+ hooks:
+ - id: black
+
+ - repo: https://github.com/astral-sh/ruff-pre-commit
+ rev: v0.0.286
+ hooks:
+ - id: ruff
+ args: [--fix, --exit-non-zero-on-fix]

CITATION.cff

@@ -1,12 +1,23 @@
+# This CITATION.cff file was generated with cffinit.
+# Visit https://bit.ly/cffinit to generate yours today!
+
 cff-version: 1.2.0
-author: Roboflow
-message: If you use this software, please cite it as below.
-title: supervision
-version: 0.11.1
-date-released: 2023-01-19
-license: MIT
-repository-code: https://github.com/roboflow/supervision
+title: Supervision
+message: >-
+ If you use this software, please cite it using the
+ metadata from this file.
+type: software
+authors:
+ - given-names: Roboflow
+ email: [email protected]
+repository-code: 'https://github.com/roboflow/supervision'
+url: 'https://roboflow.github.io/supervision/'
+abstract: >-
+ supervision features a range of utilities for use in
+ computer vision projects, from detections processing and
+ filtering to confusion matrix calcuation.
 keywords:
  - computer vision
  - image processing
- - video processing
+ - video processing
+license: MIT

CONTRIBUTING.md

@@ -14,7 +14,7 @@ We welcome contributions to:
 4. Submit a request for a new feature.
 5. Improve our test coverage.
 
-### Contributing Features
+### Contributing Features ✨
 
 Supervision is designed to provide generic utilities to solve problems. Thus, we focus on contributions that can have an impact on a wide range of projects.
 
@@ -24,29 +24,99 @@ Before you contribute a new feature, consider submitting an Issue to discuss the
 
 ## How to Contribute Changes
 
-First, fork this repository to your own GitHub account. Create a new branch that describes your changes (i.e. `line-counter-docs`). Push your changes to the branch on your fork and then submit a pull request to `develop` branch of this repository.
+First, fork this repository to your own GitHub account. Click "fork" in the top corner of the `supervision` repository to get started:
+
+![Forking the repository](https://media.roboflow.com/fork.png)
+
+![Creating a repository fork](https://media.roboflow.com/create_fork.png)
+
+Then, run `git clone` to download the project code to your computer.
+
+Move to a new branch using the `git checkout` command:
+
+```bash
+git checkout -b <your_branch_name>
+```
+
+The name you choose for your branch should describe the change you want to make (i.e. `line-counter-docs`).
+
+Make any changes you want to the project code, then run the following commands to commit your changes:
+
+```bash
+git add .
+git commit -m "Your commit message"
+git push -u origin main
+```
+
+## 🎨 Code quality
+
+### Pre-commit tool
+
+This project utilizes the [pre-commit](https://pre-commit.com/) tool to maintain code quality and consistency. Before submitting a pull request or making any commits, it is important to run the pre-commit tool to ensure that your changes meet the project's guidelines.
+
+Furthermore, we have integrated a pre-commit GitHub Action into our workflow. This means that with every pull request opened, the pre-commit checks will be automatically enforced, streamlining the code review process and ensuring that all contributions adhere to our quality standards.
+
+To run the pre-commit tool, follow these steps:
+
+1. Install pre-commit by running the following command: `poetry install`. It will not only install pre-commit but also install all the deps and dev-deps of project
+
+2. Once pre-commit is installed, navigate to the project's root directory.
+
+3. Run the command `pre-commit run --all-files`. This will execute the pre-commit hooks configured for this project against the modified files. If any issues are found, the pre-commit tool will provide feedback on how to resolve them. Make the necessary changes and re-run the pre-commit command until all issues are resolved.
+
+4. You can also install pre-commit as a git hook by execute `pre-commit install`. Every time you made `git commit` pre-commit run automatically for you.
+
+### Docstrings
+
+All new functions and classes in `supervision` should include docstrings. This is a prerequisite for any new functions and classes to be added to the library.
+
+`supervision` adheres to the [Google Python docstring style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods). Please refer to the style guide while writing docstrings for your contribution.
+
+### Type checking
+
+So far, **there is no type checking with mypy**. See [issue](https://github.com/roboflow-ai/template-python/issues/4).
+
+
+Then, go back to your fork of the `supervision` repository, click "Pull Requests", and click "New Pull Request".
+
+![Opening a pull request](https://media.roboflow.com/open_pr.png)
+
+Make sure the `base` branch is `develop` before submitting your PR.
+
+On the next page, review your changes then click "Create pull request":
+
+![Configuring a pull request](https://media.roboflow.com/create_pr_submit.png)
+
+Next, write a description for your pull request, and click "Create pull request" again to submit it for review:
+
+![Submitting a pull request](https://media.roboflow.com/write_pr.png)
 
 When creating new functions, please ensure you have the following:
 
 1. Docstrings for the function and all parameters.
 2. Unit tests for the function.
 3. Examples in the documentation for the function.
 4. Created an entry in our docs to autogenerate the documentation for the function.
-5. Please share google colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that google colab can be accessed without any issue. 
+5. Please share a Google Colab with minimal code to test new feature or reproduce PR whenever it is possible. Please ensure that Google Colab can be accessed without any issue.
+
+When you submit your Pull Request, you will be asked to sign a Contributor License Agreement (CLA) by the `cla-assistant` GitHub bot. We can only respond to PRs from contributors who have signed the project CLA.
 
 All pull requests will be reviewed by the maintainers of the project. We will provide feedback and ask for changes if necessary.
 
 PRs must pass all tests and linting requirements before they can be merged.
 
-## 🧹 code quality 
+## 📝 documentation
 
-We provide two handy commands inside the `Makefile`, namely:
+The `supervision` documentation is stored in a folder called `docs`. The project documentation is built using `mkdocs`.
 
-- `make style` to format the code
-- `make check_code_quality` to check code quality (PEP8 basically)
+To run the documentation, install the project requirements with `poetry install dev`. Then, run `mkdocs serve` to start the documentation server.
 
-So far, **there is no types checking with mypy**. See [issue](https://github.com/roboflow-ai/template-python/issues/4). 
+You can learn more about mkdocs on the [mkdocs website](https://www.mkdocs.org/).
 
-## 🧪 tests 
+## 🧪 tests
 
 [`pytests`](https://docs.pytest.org/en/7.1.x/) is used to run our tests.
+
+## 📄 license
+
+By contributing, you agree that your contributions will be licensed under an [MIT license](https://github.com/roboflow/supervision/blob/develop/LICENSE.md).

Makefile

@@ -12,11 +12,11 @@ check_code_quality:
  isort --check-only --profile black $(check_dirs)
  # stop the build if there are Python syntax errors or undefined names
  flake8 $(check_dirs) --count --select=E9,F63,F7,F82 --show-source --statistics
- # exit-zero treats all errors as warnings. E203 for black, E501 for docstring, W503 for line breaks before logical operators 
+ # exit-zero treats all errors as warnings. E203 for black, E501 for docstring, W503 for line breaks before logical operators
  flake8 $(check_dirs) --count --max-line-length=88 --exit-zero --ignore=D --extend-ignore=E203,E501,W503 --statistics
- 
+
 publish:
  poetry build
- twine upload -r testpypi dist/* -u ${PYPI_USERNAME} -p ${PYPI_TEST_PASSWORD} --verbose 
+ twine upload -r testpypi dist/* -u ${PYPI_USERNAME} -p ${PYPI_TEST_PASSWORD} --verbose
  twine check dist/*
- twine upload dist/* -u ${PYPI_USERNAME} -p ${PYPI_PASSWORD} --verbose 
+ twine upload dist/* -u ${PYPI_USERNAME} -p ${PYPI_PASSWORD} --verbose