diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 55d22db3..77321e83 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -1,3 +1,5 @@ +fail_fast: true + # See https://pre-commit.com for more information # See https://pre-commit.com/hooks.html for more hooks @@ -6,25 +8,32 @@ ci: # We therefore cannot use those dependencies in pre-commit CI. skip: - actionlint - - mypy - check-manifest - - pyright - - vulture - - pyroma - deptry - - pylint - - ruff-check - - ruff-format-diff - - ruff-check-fix - - ruff-format-fix - doc8 + - docs - interrogate + - interrogate-docs + - linkcheck + - mypy + - mypy-docs + - pylint - pyproject-fmt-check - pyproject-fmt-fix - - linkcheck - - spelling - - docs + - pyright + - pyright-docs - pyright-verifytypes + - pyroma + - ruff-check + - ruff-check-docs + - ruff-check-fix + - ruff-check-fix-docs + - ruff-format-diff + - ruff-format-diff-docs + - ruff-format-fix + - ruff-format-fix-docs + - spelling + - vulture default_install_hook_types: [pre-commit, pre-push, commit-msg] repos: @@ -66,6 +75,13 @@ repos: types_or: [python, toml] pass_filenames: false + - id: mypy-docs + name: mypy-docs + stages: [push] + entry: doccmd --language=python --command="mypy" + language: system + types_or: [markdown, rst, python, toml] + - id: check-manifest name: check-manifest stages: [push] @@ -81,6 +97,13 @@ repos: types_or: [python, toml] pass_filenames: false + - id: pyright-docs + name: pyright-docs + stages: [push] + entry: doccmd --language=python --command="pyright" + language: system + types_or: [markdown, rst, python, toml] + - id: vulture name: vulture entry: python -m vulture --min-confidence 100 --exclude .eggs @@ -107,30 +130,61 @@ repos: stages: [manual] pass_filenames: false + - id: pylint-docs + name: pylint-docs + entry: doccmd --language=python --command="pylint" --lowercase-file-name + language: system + stages: [manual] + types_or: [markdown, rst, python, toml] + - id: ruff-check name: Ruff check entry: python -m ruff check language: system types_or: [python] + - id: ruff-check-docs + name: Ruff check docs + entry: doccmd --language=python --command="ruff check" + language: system + types_or: [markdown, rst] + - id: ruff-format-diff name: Ruff format diff entry: python -m ruff format --diff language: system types_or: [python] + - id: ruff-format-diff-docs + name: Ruff format diff docs + entry: doccmd --language=python --no-pad-file --command="ruff format --diff" + language: system + types_or: [markdown, rst] + - id: ruff-check-fix name: Ruff check fix entry: python -m ruff check --fix language: system types_or: [python] + - id: ruff-check-fix-docs + name: Ruff check fix docs + entry: doccmd --language=python --command="ruff check --fix" + language: system + types_or: [markdown, rst] + - id: ruff-format-fix name: Ruff format entry: python -m ruff format language: system types_or: [python] + - id: ruff-format-fix-docs + name: Ruff format docs + entry: doccmd --language=python --no-pad-file --command="ruff format" + language: system + types_or: [markdown, rst] + - id: doc8 name: doc8 entry: python -m doc8 @@ -143,6 +197,12 @@ repos: language: system types_or: [python] + - id: interrogate-docs + name: interrogate docs + entry: doccmd --language=python --command="interrogate" + language: system + types_or: [markdown, rst] + - id: pyproject-fmt-check name: pyproject-fmt check entry: pyproject-fmt --check diff --git a/README.rst b/README.rst index 0f54838e..9e008dc3 100644 --- a/README.rst +++ b/README.rst @@ -22,38 +22,57 @@ Getting Started .. code-block:: python + """Add a target to VWS and then query it.""" + import pathlib + import uuid from vws import VWS, CloudRecoService + from vws.reports import QueryResult + - server_access_key = '[server-access-key]' - server_secret_key = '[server-secret-key]' - client_access_key = '[client-access-key]' - client_secret_key = '[client-secret-key]' - - vws_client = VWS( - server_access_key=server_access_key, - server_secret_key=server_secret_key, - ) - cloud_reco_client = CloudRecoService( - client_access_key=client_access_key, - client_secret_key=client_secret_key, - ) - name = 'my_image_name' - - image = pathlib.Path('high_quality_image.jpg') - with image.open(mode='rb') as my_image_file: - target_id = vws_client.add_target( - name=name, - width=1, - image=my_image_file, - active_flag=True, - application_metadata=None, + def add_target() -> str: + """Add a target to VWS and return its ID.""" + server_access_key = "[server-access-key]" + server_secret_key = "[server-secret-key]" + vws_client = VWS( + server_access_key=server_access_key, + server_secret_key=server_secret_key, + ) + name = "my_image_name_" + uuid.uuid4().hex + + image = pathlib.Path("high_quality_image.jpg") + with image.open(mode="rb") as my_image_file: + target_id = vws_client.add_target( + name=name, + width=1, + image=my_image_file, + active_flag=True, + application_metadata=None, + ) + vws_client.wait_for_target_processed(target_id=target_id) + + return target_id + + + def get_matching_targets() -> list[QueryResult]: + """Query VWS for matching targets.""" + client_access_key = "[client-access-key]" + client_secret_key = "[client-secret-key]" + + cloud_reco_client = CloudRecoService( + client_access_key=client_access_key, + client_secret_key=client_secret_key, ) - vws_client.wait_for_target_processed(target_id=target_id) - matching_targets = cloud_reco_client.query(image=my_image_file) - assert matching_targets[0].target_id == target_id + image = pathlib.Path("high_quality_image.jpg") + with image.open(mode="rb") as my_image_file: + return cloud_reco_client.query(image=my_image_file) + + + TARGET_ID = add_target() + MATCHING_TARGETS = get_matching_targets() + assert MATCHING_TARGETS[0].target_id == TARGET_ID Full Documentation ------------------ diff --git a/docs/source/index.rst b/docs/source/index.rst index 907096d1..912cddc1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -18,40 +18,57 @@ See the :doc:`api-reference` for full usage details. .. code-block:: python + """Add a target to VWS and then query it.""" + import pathlib + import uuid from vws import VWS, CloudRecoService + from vws.reports import QueryResult - server_access_key = '[server-access-key]' - server_secret_key = '[server-secret-key]' - client_access_key = '[client-access-key]' - client_secret_key = '[client-secret-key]' - - vws_client = VWS( - server_access_key=server_access_key, - server_secret_key=server_secret_key, - ) - cloud_reco_client = CloudRecoService( - client_access_key=client_access_key, - client_secret_key=client_secret_key, - ) - import uuid - name = 'my_image_name' + uuid.uuid4().hex - - image = pathlib.Path('high_quality_image.jpg') - with image.open(mode='rb') as my_image_file: - target_id = vws_client.add_target( - name=name, - width=1, - image=my_image_file, - active_flag=True, - application_metadata=None, - ) - vws_client.wait_for_target_processed(target_id=target_id) - matching_targets = cloud_reco_client.query(image=my_image_file) - - assert matching_targets[0].target_id == target_id - a = 1 + + def add_target() -> str: + """Add a target to VWS and return its ID.""" + server_access_key = "[server-access-key]" + server_secret_key = "[server-secret-key]" + vws_client = VWS( + server_access_key=server_access_key, + server_secret_key=server_secret_key, + ) + name = "my_image_name_" + uuid.uuid4().hex + + image = pathlib.Path("high_quality_image.jpg") + with image.open(mode="rb") as my_image_file: + target_id = vws_client.add_target( + name=name, + width=1, + image=my_image_file, + active_flag=True, + application_metadata=None, + ) + vws_client.wait_for_target_processed(target_id=target_id) + + return target_id + + + def get_matching_targets() -> list[QueryResult]: + """Query VWS for matching targets.""" + client_access_key = "[client-access-key]" + client_secret_key = "[client-secret-key]" + + cloud_reco_client = CloudRecoService( + client_access_key=client_access_key, + client_secret_key=client_secret_key, + ) + + image = pathlib.Path("high_quality_image.jpg") + with image.open(mode="rb") as my_image_file: + return cloud_reco_client.query(image=my_image_file) + + + TARGET_ID = add_target() + MATCHING_TARGETS = get_matching_targets() + assert MATCHING_TARGETS[0].target_id == TARGET_ID Testing ------- @@ -66,33 +83,47 @@ To write unit tests for code which uses this library, without using your Vuforia .. code-block:: python - import pathlib + """Add a target to VWS and then query it.""" - from mock_vws.database import VuforiaDatabase - from mock_vws import MockVWS - from vws import CloudRecoService, VWS + import pathlib + + from mock_vws import MockVWS + from mock_vws.database import VuforiaDatabase + + from vws import VWS, CloudRecoService + + + def test_add_target() -> None: + """Test adding a target to VWS.""" + with MockVWS() as mock: + database = VuforiaDatabase() + mock.add_database(database=database) + vws_client = VWS( + server_access_key=database.server_access_key, + server_secret_key=database.server_secret_key, + ) + cloud_reco_client = CloudRecoService( + client_access_key=database.client_access_key, + client_secret_key=database.client_secret_key, + ) + + image = pathlib.Path("high_quality_image.jpg") + with image.open(mode="rb") as my_image_file: + target_id = vws_client.add_target( + name="example_image_name", + width=1, + image=my_image_file, + application_metadata=None, + active_flag=True, + ) + + vws_client.wait_for_target_processed(target_id=target_id) + matching_targets = cloud_reco_client.query(image=my_image_file) + + assert matching_targets[0].target_id == target_id - with MockVWS() as mock: - database = VuforiaDatabase() - mock.add_database(database=database) - vws_client = VWS( - server_access_key=database.server_access_key, - server_secret_key=database.server_secret_key, - ) - cloud_reco_client = CloudRecoService( - client_access_key=database.client_access_key, - client_secret_key=database.client_secret_key, - ) - image = pathlib.Path('high_quality_image.jpg') - with image.open(mode='rb') as my_image_file: - target_id = vws_client.add_target( - name="example_image_name", - width=1, - image=my_image_file, - application_metadata=None, - active_flag=True, - ) + test_add_target() There are some differences between the mock and the real Vuforia. See https://vws-python-mock.readthedocs.io/en/latest/differences-to-vws.html for details. diff --git a/pyproject.toml b/pyproject.toml index 0b6da165..4e152e40 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -43,6 +43,7 @@ optional-dependencies.dev = [ "check-manifest==0.49", "deptry==0.20.0", "doc8==1.1.2", + "doccmd==2024.9.14.5", "freezegun==1.5.1", "furo==2024.8.6", "interrogate==1.7.0", @@ -122,6 +123,11 @@ lint.per-file-ignores."conftest.py" = [ "S106", ] +lint.per-file-ignores."doccmd_*.py" = [ + # Allow hardcoded secrets in documentation. + "S105", +] + lint.per-file-ignores."tests/*.py" = [ # Do not require tests to have a one-line summary. "D205",