[MSUE-232] - Add typing. Apply code linters. Update documentation

.flake8

@@ -0,0 +1,5 @@
+[flake8]
+ignore = E501,W503
+per-file-ignores = __init__.py:F401
+max-line-length = 79
+disable-noqa = true

.github/workflows/ci.yml

@@ -12,8 +12,6 @@ permissions:
   contents: read
 
 env:
-  mock_version_python3: "5.0.1"
-  requests_version_python3: "2.28.2"
   ACCOUNT_ID: ${{ secrets.ACCOUNT_ID }}
   API_KEY: ${{ secrets.API_KEY }}
 
@@ -26,10 +24,13 @@ jobs:
         uses: actions/setup-python@v3
         with:
           python-version: "3.10.14"
-      - name: Install test dependencies
+      - name: Install the library
         run: |
-          pip install mock=="${{ env.mock_version_python3 }}"
-          pip install requests=="${{ env.requests_version_python3 }}"
+          pip install -e .
+      - name: Run linters
+        run: |
+          pip install -U pre-commit
+          pre-commit run -v --all-files
       - name: Run tests
         run: |
           python -m unittest discover
@@ -43,7 +44,7 @@ jobs:
         uses: actions/setup-python@v3
         with:
           python-version: "3.10.14"
-      - name: run-integration-tests-python3
+      - name: Run integration tests
         run: |
-          pip3 install .
-          python3 test_integration_app/main.py
+          pip install .
+          python test_integration_app/main.py

.github/workflows/publishing2PyPI.yml

@@ -18,7 +18,7 @@ jobs:
           VERSION=$(cat ./sift/version.py | grep -E -i '^VERSION.*' | cut -d'=' -f2 | cut -d\' -f2)
           [[ $VERSION == "NOT_SET" ]] && echo "Version in version.py NOT_SET" && exit 1
           echo "curr_version=$(echo $VERSION)" >> $GITHUB_ENV
-      - name: Compare package version and Releas tag
+      - name: Compare package version and Release tag
         run: |
           TAG=${GITHUB_REF##*/}
           if [[ $TAG != *"$curr_version"* ]]; then
@@ -27,11 +27,12 @@ jobs:
           fi
       - name: Create distribution files
         run: |
-          python3 setup.py sdist
+          python -m pip install build
+          python -m build
       - name: Upload distribution files
         env:
           TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
           TWINE_USER: ${{ secrets.USER }}
         run: |
-          python3 -m pip install --user --upgrade twine
-          ls  dist/ | xargs  -I % python3 -m twine upload --repository pypi dist/%
+          python -m pip install --user --upgrade twine
+          ls  dist/ | xargs  -I % python -m twine upload --repository pypi dist/%

.gitignore

@@ -1,3 +1,4 @@
+__pycache__
 *.py[cod]
 
 # C extensions

.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.31.1
+    hooks:
+      - id: typos
+        args: [ --force-exclude ]
+  - repo: https://github.com/pycqa/isort
+    rev: 5.13.2
+    hooks:
+      - id: isort
+  - repo: https://github.com/psf/black
+    rev: 24.8.0
+    hooks:
+      - id: black
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.1.2
+    hooks:
+      - id: flake8
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+      - id: mypy
+        args: [ --install-types, --non-interactive ]
+        additional_dependencies: [ types-requests ]

CHANGES.md

@@ -1,3 +1,24 @@
+6.0.0 2025-05-05
+================
+
+- Added support for Python 3.13
+- Dropped support for Python < 3.8
+- Added typing annotations overall the library
+- Updated doc strings with actual information
+- Fixed an issue when the client could send requests with invalid version in the "User-Agent" header
+- Changed the type of the `abuse_types` parameter in the `client.get_decisions()` method
+
+INCOMPATIBLE CHANGES INTRODUCED IN 6.0.0:
+
+- Dropped support for Python < 3.8
+- Passing `abuse_types` as a comma-separated string to the `client.get_decisions()` is deprecated.
+
+  Previously, `client.get_decisions()` method allowed to pass `abuse_types` parameter as a
+  comma-separated string e.g. `abuse_types="legacy,payment_abuse"`. This is deprecated now.
+  Starting from 6.0.0 callers must pass `abuse_types` parameter to the `client.get_decisions()`
+  method as a sequence of string literals e.g. `abuse_types=("legacy", "payment_abuse")`. The same
+  way as it passed to the other client's methods which receive `abuse_types` parameter.
+
 5.6.1 2024-10-08
 - Updated implementation to use Basic Authentication instead of passing `API_KEY` as a request parameter for the following calls:
   - `client.score()`
@@ -127,7 +148,7 @@ INCOMPATIBLE CHANGES INTRODUCED IN API V205:
 1.1.2.0 (2015-02-04)
 ====================
 
--   Added Unlabel functionaly
+-   Added Unlabel functionality
 -   Minor bug fixes.
 
 1.1.1.0 (2014-09-3)

CONTRIBUTING.md

@@ -0,0 +1,69 @@
+
+## Setting up the environment
+
+1. Install [pyenv](https://github.com/pyenv/pyenv?tab=readme-ov-file#installation)
+2. Setup virtual environment
+
+```sh
+# install necessary Python version
+pyenv install 3.13.2
+
+# create a virtual environment
+pyenv virtualenv 3.13.2 v3.13
+pyenv activate v3.13
+```
+
+3. Upgrade pip
+
+```sh
+pip install -U pip
+```
+
+4. Install pre-commit
+
+```sh
+pip install -U pre-commit
+pre-commit install
+```
+
+5. Install the library:
+
+```sh
+pip install -e .
+```
+
+## Testing
+
+Before submitting a change, make sure the following commands run without
+errors from the root folder of the repository:
+
+```sh
+python -m unittest discover
+```
+
+## Integration testing app
+
+For testing the app with real calls it is possible to run the integration testing app,
+it makes calls to almost all Sift public API endpoints to make sure the library integrates
+well. At the moment, the app is run on every merge to master
+
+#### How to run it locally
+
+1. Add env variable `API_KEY` with the valid Api Key associated from the account
+
+```sh
+export API_KEY="api_key"
+```
+
+1. Add env variable `ACCOUNT_ID` with the valid account id
+
+```sh
+export ACCOUNT_ID="account_id"
+```
+
+3. Run the following under the project root folder
+
+```sh
+# run the app
+python test_integration_app/main.py
+```

README.md

@@ -1,45 +1,22 @@
 # Sift Python Bindings
 
 Bindings for Sift's APIs -- including the
-[Events](https://sift.com/resources/references/events-api.html),
-[Labels](https://sift.com/resources/references/labels-api.html),
+[Events](https://developers.sift.com/docs/python/events-api/,
+[Labels](https://developers.sift.com/docs/python/labels-api/),
 and
-[Score](https://sift.com/resources/references/score-api.html)
+[Score](https://developers.sift.com/docs/python/score-api/)
 APIs.
 
-
 ## Installation
 
-Set up a virtual environment with virtualenv (otherwise you will need
-to make the pip calls as sudo):
-
-    virtualenv venv
-    source venv/bin/activate
-
-Get the latest released package from pip:
-
-Python 2:
-
-    pip install Sift
-
-Python 3:
-
-    pip3 install Sift
-
-or install newest source directly from GitHub:
-
-Python 2:
-
-    pip install git+https://github.com/SiftScience/sift-python
-
-Python 3:
-
-    pip3 install git+https://github.com/SiftScience/sift-python
-
+```sh
+# install from PyPi
+pip install Sift
+```
 
 ## Documentation
 
-Please see [here](https://sift.com/developers/docs/python/events-api/overview) for the
+Please see [here](https://developers.sift.com/docs/python/apis-overview) for the
 most up-to-date documentation.
 
 ## Changelog
@@ -48,19 +25,13 @@ Please see
 [the CHANGELOG](https://github.com/SiftScience/sift-python/blob/master/CHANGES.md)
 for a history of all changes.
 
-Note, that in v2.0.0, the API semantics were changed to raise an
-exception in the case of error to be more pythonic. Client code will
-need to be updated to catch `sift.client.ApiException` exceptions.
-
-
 ## Usage
 
 Here's an example:
 
 ```python
 
-import json
-import sift.client
+import sift
 
 client = sift.Client(api_key='<your API key here>', account_id='<your account ID here>')
 
@@ -85,12 +56,17 @@ properties = {
 }
 
 try:
-    response = client.track("$transaction", properties)
-    if response.is_ok():
-        print "Successfully tracked event"
+    response = client.track(
+        "$transaction",
+        properties,
+    )
 except sift.client.ApiException:
     # request failed
     pass
+else:
+    if response.is_ok():
+        print("Successfully tracked event")
+
 
 # Track a transaсtion event and receive a score with percentiles in response (sync flow).
 # Note: `return_score` or `return_workflow_status` must be set `True`.
@@ -111,15 +87,24 @@ properties = {
 }
 
 try:
-    response = client.track("$transaction", properties, return_score=True, include_score_percentiles=True, abuse_types=["promotion_abuse", "content_abuse", "payment_abuse"])
-    if response.is_ok():
-        score_response = response.body["score_response"]
-        print(score_response)
+    response = client.track(
+        "$transaction",
+        properties,
+        return_score=True,
+        include_score_percentiles=True,
+        abuse_types=("promotion_abuse", "content_abuse", "payment_abuse"),
+    )
 except sift.client.ApiException:
     # request failed
     pass
+else:
+    if response.is_ok():
+        score_response = response.body["score_response"]
+        print(score_response)
+
 
-# To include `warnings` field to Events API response via calling `track()` method, set it by the `include_warnings` param:
+# In order to include `warnings` field to Events API response via calling
+# `track()` method, set it by the `include_warnings` param:
 try:
     response = client.track("$transaction", properties, include_warnings=True)
     # ...
@@ -130,12 +115,12 @@ except sift.client.ApiException:
 # Request a score for the user with user_id 23056
 try:
     response = client.score(user_id)
-    s = json.dumps(response.body)
-    print s
-
 except sift.client.ApiException:
     # request failed
     pass
+else:
+    print(response.body)
+
 
 try:
     # Label the user with user_id 23056 as Bad with all optional fields
@@ -211,6 +196,7 @@ send_properties = {
 		}
 	}
 }
+
 try:
     response = client.verification_send(send_properties)
 except sift.client.ApiException:
@@ -241,35 +227,4 @@ try:
 except sift.client.ApiException:
     # request failed
     pass
-
-```
-
-## Testing
-
-Before submitting a change, make sure the following commands run without
-errors from the root dir of the repository:
-
-    python -m unittest discover
-    python3 -m unittest discover
-
-## Integration testing app
-
-For testing the app with real calls it is possible to run the integration testing app, 
-it makes calls to almost all our public endpoints to make sure the library integrates
-well. At the moment, the app is run on every merge to master
-
-#### How to run it locally
-
-1. Add env variable `ACCOUNT_ID` with the valid account id
-2. Add env variable `API_KEY` with the valid Api Key associated from the account
-3. Run the following under the project root folder
-```
-# uninstall the lib from the local env (if it was installed)
-pip uninstall sift
-
-# install the lib from the local source code
-pip install ../sift-python
-
-# run the app
-python test_integration_app/main.py
 ```