Update documentation & packaging

.github/workflows/build-golang-macos.yaml

@@ -97,7 +97,7 @@ jobs:
         - name: Test Python wheel
           run: |
               # Test wheel installation
-              pip install dist/otdf_python-0.0.10-py3-none-any.whl
+              pip install dist/otdf_python-0.0.11-py3-none-any.whl
 
               # Test wheel functionality
               # python3 validate_otdf_python.py

.github/workflows/build-golang-ubuntu.yaml

@@ -127,7 +127,7 @@ jobs:
             - name: Test Python wheel
               run: |
                   # Test wheel installation
-                  pip install dist/otdf_python-0.0.10-py3-none-any.whl
+                  pip install dist/otdf_python-0.0.11-py3-none-any.whl
 
                   # DISABLED: Need to figure out Ubuntu nested VM
                   # Test wheel functionality

.pre-commit-config.yaml

@@ -37,3 +37,12 @@ repos:
       hooks:
           - id: codespell
             args: ["--ignore-words-list", "b-long, otdf_python", "--skip=go.sum,otdf_python/"]
+
+    - repo: https://github.com/astral-sh/ruff-pre-commit
+      # Ruff version.
+      rev: v0.6.7
+      hooks:
+        # Run the linter.
+        - id: ruff
+        # Run the formatter.
+        - id: ruff-format

README.md

@@ -15,4 +15,60 @@ pip install otdf_python
 
 ## Usage
 
-See `validate_otdf_python.py` for usage examples.
+Simple usage examples are given below.  In addition, see the content of `validate_otdf_python.py` .
+
+### Example: Encrypt a string
+
+```python
+from otdf_python.gotdf_python import EncryptString
+
+config: EncryptionConfig = _get_configuration()
+
+tdf_manifest_json = EncryptString(inputText="Hello from Python", config=config)
+
+```
+
+### Example: Encrypt a file
+
+```python
+from otdf_python.gotdf_python import EncryptFile
+from otdf_python.go import Slice_string
+
+with tempfile.TemporaryDirectory() as tmpDir:
+    print("Created temporary directory", tmpDir)
+
+    da = Slice_string(["https://example.com/attr/attr1/value/value1", "https://example.com/attr/attr1/value/value2"])
+
+    config: EncryptionConfig = EncryptionConfig(
+        ClientId="opentdf-sdk",
+        ClientSecret="secret",
+        PlatformEndpoint=platformEndpoint,
+        TokenEndpoint="http://localhost:8888/auth/realms/opentdf/protocol/openid-connect/token",
+        KasUrl=f"http://{platformEndpoint}/kas",
+        # FIXME: Be careful with binding the 'DataAttributes' field on this struct.
+        #
+        # In golang, this is initialized as []string , but passing
+        # DataAttributes=None, or DataAttributes=[] from Python will fail.
+        # DataAttributes=...
+        DataAttributes=da,
+    )
+
+    encrypted_file = Path(tmpDir) / "some-file.tdf"
+
+    if encrypted_file.exists():
+        encrypted_file.unlink()
+
+    if encrypted_file.exists():
+        raise ValueError(
+            "The output path should not exist before calling 'EncryptFile()'."
+        )
+
+    outputFilePath = EncryptFile(
+        inputFilePath=str(SOME_PLAINTEXT_FILE),
+        outputFilePath=str(encrypted_file),
+        config=config,
+    )
+
+    print(f"The output file was written to destination path: {outputFilePath}")
+
+```

pyproject.toml

@@ -1,7 +1,7 @@
 [tool.poetry]
 name = "otdf-python"
 # Should match 'setup.py' version number (used for gopy/pybindgen)
-version = "0.0.10"
+version = "0.0.11"
 description = ""
 authors = ["b-long <b-long@users.noreply.github.com>"]
 readme = "README.md"

setup.py

@@ -1,7 +1,19 @@
 import setuptools
 
-with open("README.md", "r") as fh:
-    long_description = fh.read()
+
+from pathlib import Path
+
+"""
+NOTE: This project uses more than one version of a 'setup.py' file:
+* 'setup.py', and
+* 'setup_ci.py'
+
+Based on:
+    https://github.com/popatam/gopy_build_wheel_example/blob/main/setup_ci.py
+"""
+
+this_directory = Path(__file__).parent
+long_description = (this_directory / "README.md").read_text()
 
 setuptools.setup(
     name="otdf_python",
@@ -12,7 +24,7 @@
     url="https://github.com/b-long/opentdf-python-sdk",
     package_data={"otdf_python": ["*.so"]},
     # Should match 'pyproject.toml' version number
-    version="0.0.10",
+    version="0.0.11",
     author_email="b-long@users.noreply.github.com",
     include_package_data=True,
 )

setup_ci.py

@@ -4,34 +4,39 @@
 import sys
 import re
 from distutils.core import Extension
+from pathlib import Path
 
 import setuptools
 from setuptools.command.build_ext import build_ext
 
 """
+NOTE: This project uses more than one version of a 'setup.py' file:
+* 'setup.py', and
+* 'setup_ci.py'
+
 Based on:
     https://github.com/popatam/gopy_build_wheel_example/blob/main/setup_ci.py
 """
 
+
 def normalize(name):  # https://peps.python.org/pep-0503/#normalized-names
     return re.sub(r"[-_.]+", "-", name).lower()
 
-# PACKAGE_PATH="simple_go_timer"
-# PACKAGE_NAME=PACKAGE_PATH.split("/")[-1]
 
-PACKAGE_PATH="gotdf_python"
-PACKAGE_NAME="otdf_python"
+PACKAGE_PATH = "gotdf_python"
+PACKAGE_NAME = "otdf_python"
 
-if sys.platform == 'darwin':
+if sys.platform == "darwin":
     # PYTHON_BINARY_PATH is setting explicitly for 310 and 311, see build_wheel.yml
     # on macos PYTHON_BINARY_PATH must be python bin installed from python.org or from brew
     PYTHON_BINARY = os.getenv("PYTHON_BINARY_PATH", sys.executable)
     if PYTHON_BINARY == sys.executable:
-        subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'pybindgen'])
+        subprocess.check_call([sys.executable, "-m", "pip", "install", "pybindgen"])
 else:
     # linux & windows
     PYTHON_BINARY = sys.executable
-    subprocess.check_call([sys.executable, '-m', 'pip', 'install', 'pybindgen'])
+    subprocess.check_call([sys.executable, "-m", "pip", "install", "pybindgen"])
+
 
 def _generate_path_with_gopath() -> str:
     go_path = subprocess.check_output(["go", "env", "GOPATH"]).decode("utf-8").strip()
@@ -42,9 +47,14 @@ def _generate_path_with_gopath() -> str:
 class CustomBuildExt(build_ext):
     def build_extension(self, ext: Extension):
         bin_path = _generate_path_with_gopath()
-        go_env = json.loads(subprocess.check_output(["go", "env", "-json"]).decode("utf-8").strip())
+        go_env = json.loads(
+            subprocess.check_output(["go", "env", "-json"]).decode("utf-8").strip()
+        )
 
-        destination = os.path.dirname(os.path.abspath(self.get_ext_fullpath(ext.name))) + f"/{PACKAGE_NAME}"
+        destination = (
+            os.path.dirname(os.path.abspath(self.get_ext_fullpath(ext.name)))
+            + f"/{PACKAGE_NAME}"
+        )
 
         subprocess.check_call(
             [
@@ -65,15 +75,17 @@ def build_extension(self, ext: Extension):
         with open(f"{destination}/__init__.py", "w") as f:
             f.write(f"from .{PACKAGE_PATH} import *")
 
-with open("README.md", "r") as fh:
-    long_description = fh.read()
+
+this_directory = Path(__file__).parent
+long_description = (this_directory / "README.md").read_text()
 
 setuptools.setup(
     name="otdf_python",
-    version="0.0.10",
+    version="0.0.11",
     author="b-long",
-    long_description=long_description,
     description="Unofficial OpenTDF SDK for Python.",
+    long_description_content_type="text/markdown",
+    long_description=long_description,
     url="https://github.com/b-long/opentdf-python-sdk",
     classifiers=[
         "Programming Language :: Python :: 3",
@@ -85,6 +97,9 @@ def build_extension(self, ext: Extension):
         "build_ext": CustomBuildExt,
     },
     ext_modules=[
-        Extension(PACKAGE_NAME, [PACKAGE_PATH],)
+        Extension(
+            PACKAGE_NAME,
+            [PACKAGE_PATH],
+        )
     ],
 )

validate_otdf_python.py

@@ -19,7 +19,6 @@ def verify_hello():
 
 
 def _get_configuration() -> EncryptionConfig:
-
     platformEndpoint = "localhost:8080"
 
     config: EncryptionConfig = EncryptionConfig(