diff --git a/.github/workflows/pytest-linux.yaml b/.github/workflows/pytest-linux.yaml index 62afb7d..1ffaf95 100644 --- a/.github/workflows/pytest-linux.yaml +++ b/.github/workflows/pytest-linux.yaml @@ -78,6 +78,7 @@ jobs: set +e pytest \ examples/misc/ \ + examples/docs/ \ examples/extras/ \ examples/szabstractfactory/ \ examples/szconfig/ \ diff --git a/docs/source/index.rst b/docs/source/index.rst index 6a6a205..e3e5194 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -3,8 +3,30 @@ You can adapt this file completely to your liking, but it should at least contain the root `toctree` directive. -Welcome to sz-sdk-python's documentation! -========================================= +`senzing` Python package documentation +====================================== + +The `senzing`_ Python package contains the interface definitions +for the `senzing-core`_ and `senzing-grpc`_ implementation packages. + +By using interface definitions, implementation-agnostic code can be written. +For example, the following code does not need to know the underlying implementation +of the Senzing Abstract Factory: + +.. literalinclude:: ../../examples/docs/using_abstract_factory.py + :linenos: + :language: python + +Similarly, interface definitions for Senzing objects can be used. +Example: + +.. literalinclude:: ../../examples/docs/using_sz_engine.py + :linenos: + :language: python + +Senzing has additional Software Development Kits (SDKs) +for Java, Go, and C#. +Information for these SDKs can be found at `docs.senzing.com`_. .. toctree:: :maxdepth: 2 @@ -20,3 +42,8 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + +.. _docs.senzing.com: https://www.senzing.com/docs +.. _senzing: https://github.com/senzing-garage/sz-sdk-python +.. _senzing-core: https://garage.senzing.com/sz-sdk-python-core +.. _senzing-grpc: https://garage.senzing.com/sz-sdk-python-grpc diff --git a/docs/source/modules.rst b/docs/source/modules.rst index 2d78ffc..1c041a9 100644 --- a/docs/source/modules.rst +++ b/docs/source/modules.rst @@ -1,7 +1,35 @@ senzing ======= +The `senzing` Python package has 5 major modules / classes. +Senzing objects are created using an `Abstract Factory Pattern`_. + +.. list-table:: Senzing classes + :widths: 20 20 60 + :header-rows: 1 + + * - Module + - Class + - Creation + * - szconfig + - SzConfig + - `sz_config = sz_abstract_factory.create_config()` + * - szconfigmanager + - SzConfigManager + - `sz_configmanager = sz_abstract_factory.create_configmanager()` + * - szdiagnostic + - SzDiagnostic + - `sz_diagnostic = sz_abstract_factory.create_diagnostic()` + * - szengine + - SzEngine + - `sz_engine = sz_abstract_factory.create_engine()` + * - szproduct + - SzProduct + - `sz_product = sz_abstract_factory.create_product()` + .. toctree:: :maxdepth: 4 senzing + +.. _Abstract Factory Pattern: https://en.wikipedia.org/wiki/Abstract_factory_pattern \ No newline at end of file diff --git a/docs/source/senzing.rst b/docs/source/senzing.rst index 430747f..e1f6b35 100644 --- a/docs/source/senzing.rst +++ b/docs/source/senzing.rst @@ -1,6 +1,29 @@ senzing package =============== +In the examples, the creation of the Senzing objects has been abstracted to + +.. literalinclude:: ../../examples/docs/import_sz_abstract_factory.py + :linenos: + :language: python + +and + +.. literalinclude:: ../../examples/docs/import_sz_engine.py + :linenos: + :language: python + +Using the `senzing-core` Python package, the implementation looks like the following: + + +.. literalinclude:: ../../examples/helpers/setup_senzing.py + :linenos: + :language: python + +Naturally, the `__init__.py` file needs to be modified to support importing the variables. +For the full implementation of the documentation examples, visit the source code on +`GitHub`_. + Submodules ---------- @@ -67,3 +90,6 @@ Module contents :members: :undoc-members: :show-inheritance: + + +.. _GitHub: https://github.com/senzing-garage/sz-sdk-python/tree/main/examples \ No newline at end of file diff --git a/examples/docs/__init__.py b/examples/docs/__init__.py new file mode 100644 index 0000000..faf47d9 --- /dev/null +++ b/examples/docs/__init__.py @@ -0,0 +1,13 @@ +from ..helpers.setup_senzing import ( + get_sz_abstract_factory, + get_sz_engine, + sz_abstract_factory, + sz_engine, +) + +__all__ = [ + "get_sz_abstract_factory", + "get_sz_engine", + "sz_abstract_factory", + "sz_engine", +] diff --git a/examples/docs/a_header_docs.py b/examples/docs/a_header_docs.py new file mode 100755 index 0000000..8d0cebb --- /dev/null +++ b/examples/docs/a_header_docs.py @@ -0,0 +1,5 @@ +""" +Simply a header used in development. +""" + +print("\n---- docs ------------------------------------------------------------\n") diff --git a/examples/docs/import_sz_abstract_factory.py b/examples/docs/import_sz_abstract_factory.py new file mode 100644 index 0000000..b3983d0 --- /dev/null +++ b/examples/docs/import_sz_abstract_factory.py @@ -0,0 +1,3 @@ +from . import sz_abstract_factory + +sz_engine = sz_abstract_factory.create_engine() diff --git a/examples/docs/import_sz_engine.py b/examples/docs/import_sz_engine.py new file mode 100644 index 0000000..afb104d --- /dev/null +++ b/examples/docs/import_sz_engine.py @@ -0,0 +1,3 @@ +from . import sz_engine + +count = sz_engine.count_redo_records() diff --git a/examples/docs/using_abstract_factory.py b/examples/docs/using_abstract_factory.py new file mode 100644 index 0000000..f7dda4f --- /dev/null +++ b/examples/docs/using_abstract_factory.py @@ -0,0 +1,8 @@ +from senzing import SzAbstractFactory, SzEngineFlags + + +def perform_senzing_search(sz_abstract_factory: SzAbstractFactory, attributes: str) -> str: + sz_engine = sz_abstract_factory.create_engine() + flags = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS + search_profile = "" + return sz_engine.search_by_attributes(attributes, flags, search_profile) diff --git a/examples/docs/using_sz_engine.py b/examples/docs/using_sz_engine.py new file mode 100644 index 0000000..7442129 --- /dev/null +++ b/examples/docs/using_sz_engine.py @@ -0,0 +1,7 @@ +from senzing import SzEngine, SzEngineFlags + + +def perform_senzing_search(sz_engine: SzEngine, attributes: str) -> str: + flags = SzEngineFlags.SZ_SEARCH_BY_ATTRIBUTES_DEFAULT_FLAGS + search_profile = "" + return sz_engine.search_by_attributes(attributes, flags, search_profile) diff --git a/examples/helpers/setup_senzing.py b/examples/helpers/setup_senzing.py index 8c43303..5e26e61 100755 --- a/examples/helpers/setup_senzing.py +++ b/examples/helpers/setup_senzing.py @@ -23,12 +23,10 @@ def get_sz_abstract_factory() -> SzAbstractFactory: """Example AbstractFactory""" - try: result = SzAbstractFactoryCore(INSTANCE_NAME, SETTINGS) except SzError as err: print(f"\nERROR: {err}\n") - return result diff --git a/makefiles/linux.mk b/makefiles/linux.mk index c5657af..7ee21af 100644 --- a/makefiles/linux.mk +++ b/makefiles/linux.mk @@ -71,6 +71,7 @@ test-osarch-specific: $(info --- Test examples using pytest -------------------------------------) @$(activate-venv); pytest \ examples/misc/ \ + examples/docs/ \ examples/extras/ \ examples/szabstractfactory/ \ examples/szconfig/ \