feat(cli): Streamline CLI and improve documentation

This commit enhances the self-encryption CLI interface and documentation: Core Changes: - Simplified CLI invocation to just `self_encryption` instead of requiring `.cli` - Added direct module execution via `__main__.py` - Configured console script entry point in pyproject.toml Documentation Improvements: - Added comprehensive docstrings to Python bindings (src/python.rs) - Enhanced CLI command documentation with detailed examples - Added clear process descriptions for encryption/decryption flows - Included type hints and return value documentation Technical Details: - Updated PyO3 bindings documentation with usage examples - Added detailed error descriptions and exception handling - Improved streaming operation documentation - Added parameter descriptions for all CLI commands The CLI can now be invoked directly: $ self_encryption encrypt-file input.dat chunks/ $ self_encryption decrypt-file data_map.json chunks/ output.dat This change makes the tool more user-friendly while maintaining all existing functionality and adding better documentation for users and developers.
maidsafe · Dec 24, 2024 · f93fc6c · f93fc6c
1 parent a9d4bae
commit f93fc6c
Show file tree

Hide file tree

Showing 18 changed files with 1,536 additions and 1,040 deletions.
diff --git a/.github/workflows/python-publish.yml b/.github/workflows/python-publish.yml
@@ -30,12 +30,12 @@ jobs:
         uses: PyO3/maturin-action@v1
         with:
           target: ${{ matrix.target }}
-          args: --release --out dist
+          args: --release --out dist -i python${{ matrix.python-version }}
           sccache: 'true'
       - name: Upload wheels
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v4
         with:
-          name: wheels
+          name: wheels-macos-${{ matrix.target }}-py${{ matrix.python-version }}
           path: dist/*.whl
           if-no-files-found: error
 
@@ -72,68 +72,28 @@ jobs:
     strategy:
       matrix:
         target: [x86_64, i686]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: ${{ matrix.python-version }}
           architecture: x64
       - name: Build wheels
-        uses: messense/maturin-action@v1
-        with:
-          target: ${{ matrix.target }}
-          manylinux: auto
-          args: --release --out dist
-          maturin-version: "v0.13.0"
-      - name: Install built wheel
-        if: matrix.target == 'x86_64'
-        run: |
-          pip install dist/${{ env.PACKAGE_NAME }}-*.whl --force-reinstall
-          pip install pytest
-          pytest -v
-      - name: Upload wheels
-        uses: actions/upload-artifact@v2
-        with:
-          name: wheels
-          path: dist
-
-  linux-cross:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        target: [aarch64, armv7, s390x, ppc64le, ppc64]
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-      - name: Build wheels
-        uses: messense/maturin-action@v1
+        uses: PyO3/maturin-action@v1
+        env:
+          PYTHON_VERSION: ${{ matrix.python-version }}
         with:
           target: ${{ matrix.target }}
           manylinux: auto
-          args: --release --out dist
-          maturin-version: "v0.13.0"
-      - uses: uraimo/[email protected]
-        if: matrix.target != 'ppc64'
-        name: Install built wheel
-        with:
-          arch: ${{ matrix.target }}
-          distro: ubuntu20.04
-          githubToken: ${{ github.token }}
-          install: |
-            apt-get update
-            apt-get install -y --no-install-recommends python3 python3-pip
-            pip3 install -U pip
-          run: |
-            pip3 install ${{ env.PACKAGE_NAME }} --no-index --find-links dist/ --force-reinstall
-            pip install pytest
-            pytest -v
+          args: --release --out dist -i python${{ matrix.python-version }}
+          sccache: 'true'
       - name: Upload wheels
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
-          name: wheels
-          path: dist
+          name: wheels-linux-${{ matrix.target }}-py${{ matrix.python-version }}
+          path: dist/*.whl
+          if-no-files-found: error
 
   musllinux:
     runs-on: ubuntu-latest
@@ -142,75 +102,29 @@ jobs:
         target:
           - x86_64-unknown-linux-musl
           - i686-unknown-linux-musl
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4
         with:
-          python-version: ${{ env.PYTHON_VERSION }}
+          python-version: ${{ matrix.python-version }}
           architecture: x64
       - name: Build wheels
-        uses: messense/maturin-action@v1
+        uses: PyO3/maturin-action@v1
+        env:
+          PYO3_CROSS_PYTHON_VERSION: ${{ matrix.python-version }}
+          PYO3_CROSS: "1"
         with:
           target: ${{ matrix.target }}
           manylinux: musllinux_1_2
-          args: --release --out dist
-          maturin-version: "v0.13.0"
-      - name: Install built wheel
-        if: matrix.target == 'x86_64-unknown-linux-musl'
-        uses: addnab/docker-run-action@v3
-        with:
-          image: alpine:latest
-          options: -v ${{ github.workspace }}:/io -w /io
-          run: |
-            apk add py3-pip
-            pip3 install -U pip pytest
-            pip3 install ${{ env.PACKAGE_NAME }} --no-index --find-links /io/dist/ --force-reinstall
-            python3 -m pytest
-      - name: Upload wheels
-        uses: actions/upload-artifact@v2
-        with:
-          name: wheels
-          path: dist
-
-  musllinux-cross:
-    runs-on: ubuntu-latest
-    strategy:
-      matrix:
-        platform:
-          - target: aarch64-unknown-linux-musl
-            arch: aarch64
-          - target: armv7-unknown-linux-musleabihf
-            arch: armv7
-    steps:
-      - uses: actions/checkout@v3
-      - uses: actions/setup-python@v4
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-      - name: Build wheels
-        uses: messense/maturin-action@v1
-        with:
-          target: ${{ matrix.platform.target }}
-          manylinux: musllinux_1_2
-          args: --release --out dist
-          maturin-version: "v0.13.0"
-      - uses: uraimo/run-on-arch-action@master
-        name: Install built wheel
-        with:
-          arch: ${{ matrix.platform.arch }}
-          distro: alpine_latest
-          githubToken: ${{ github.token }}
-          install: |
-            apk add py3-pip
-            pip3 install -U pip pytest
-          run: |
-            pip3 install ${{ env.PACKAGE_NAME }} --no-index --find-links dist/ --force-reinstall
-            python3 -m pytest
+          args: --release --out dist -i python${{ matrix.python-version }}
+          sccache: 'true'
       - name: Upload wheels
-        uses: actions/upload-artifact@v2
+        uses: actions/upload-artifact@v4
         with:
-          name: wheels
-          path: dist
-
+          name: wheels-musllinux-${{ matrix.target }}-py${{ matrix.python-version }}
+          path: dist/*.whl
+          if-no-files-found: error
 
   sdist:
     runs-on: ubuntu-latest
@@ -235,7 +149,7 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
-    needs: [macos, windows, linux, sdist]
+    needs: [macos, windows, linux, musllinux, sdist]
     # Keep existing permissions
     permissions:
       id-token: write
@@ -252,4 +166,5 @@ jobs:
         with:
           packages-dir: dist/
           verbose: true
-          print-hash: true
+          print-hash: true
+
diff --git a/.gitignore b/.gitignore
@@ -22,6 +22,11 @@ target/
 *.whl
 *.so 
 *pyc*
+venv/
+.venv/
+.cursorrules
+.windsurfrules
+test_chunks/
 
 
 
diff --git a/Cargo.toml b/Cargo.toml
@@ -8,11 +8,14 @@ license = "GPL-3.0"
 name = "self_encryption"
 readme = "README.md"
 repository = "https://github.com/maidsafe/self_encryption"
-version = "0.32.4"
+version = "0.32.41"
 
 [features]
 default = []
-python = ["pyo3/extension-module"]
+python = [
+    "pyo3/extension-module",
+    "serde_json"
+]
 
 [dependencies]
 aes = "~0.8.1"
@@ -23,10 +26,12 @@ rand = "~0.8.5"
 rand_chacha = "~0.3.1"
 rayon = "1.5.1"
 thiserror = "1.0"
+num_cpus = "1.13.0"
 itertools = "~0.10.0"
 tempfile = "3.6.0"
 xor_name = "5.0.0"
 pyo3 = { version = "=0.20.3", optional = true, features = ["extension-module"] }
+serde_json = { version = "1.0", optional = true }
 
 [dependencies.brotli]
 version = "~3.3.0"

diff --git a/__init__.py b/__init__.py
@@ -0,0 +1,32 @@
+try:
+    from ._self_encryption import (
+        PyDataMap as DataMap,
+        PyXorName as XorName,
+        EncryptResult,
+        encrypt_from_file,
+        decrypt_from_storage,
+        streaming_decrypt_from_storage,
+        MIN_CHUNK_SIZE,
+        MIN_ENCRYPTABLE_BYTES,
+        MAX_CHUNK_SIZE,
+        COMPRESSION_QUALITY,
+    )
+    from .cli import cli
+except ImportError as e:
+    import sys
+    print(f"Error importing self_encryption: {e}", file=sys.stderr)
+    raise
+
+__all__ = [
+    'DataMap',
+    'XorName',
+    'EncryptResult',
+    'encrypt_from_file',
+    'decrypt_from_storage',
+    'streaming_decrypt_from_storage',
+    'MIN_CHUNK_SIZE',
+    'MIN_ENCRYPTABLE_BYTES',
+    'MAX_CHUNK_SIZE',
+    'COMPRESSION_QUALITY',
+    'cli',
+]