Development

.github/workflows/docs.yml

@@ -0,0 +1,43 @@
+name: website
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+      - run: pip install -e .
+      - run: pip install pdoc
+      - run: pdoc -d google pyoutlineapi --output-dir docs
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/python_tests.yml

@@ -5,38 +5,88 @@ on:
     branches: [ "main", "development" ]
   pull_request:
     branches: [ "main" ]
+  schedule:
+    - cron: '0 0 * * 0'  # Weekly security scan
 
 permissions:
   contents: read
+  pull-requests: write
+  security-events: write  # Required for security findings
 
 jobs:
-  build:
+  test:
+    name: Run Tests
     runs-on: ubuntu-latest
 
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12", "3.13" ]
+
     steps:
       - uses: actions/checkout@v4
-      - name: Set up Python 3.12
-        uses: actions/setup-python@v3
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
+          cache: 'pip'
+
       - name: Install Poetry
-        run: |
-          curl -sSL https://install.python-poetry.org | python3 -
-          echo "export PATH=$HOME/.local/bin:$PATH" >> $GITHUB_ENV
+        uses: snok/install-poetry@v1
+        with:
+          virtualenvs-create: true
+          virtualenvs-in-project: true
+          installer-parallel: true
+
+      - name: Load cached venv
+        id: cached-poetry-dependencies
+        uses: actions/cache@v4
+        with:
+          path: .venv
+          key: venv-${{ runner.os }}-${{ matrix.python-version }}-${{ hashFiles('**/poetry.lock') }}
+
       - name: Install dependencies
+        if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+        run: poetry install --no-interaction
+
+      - name: Run tests
         run: |
-          poetry install
-      - name: Install flake8
-        run: |
-          poetry run pip install flake8
-      - name: Lint with flake8
+          poetry run pytest --cov=./ --cov-report=xml
+
+      - name: Upload coverage to Codecov
+        uses: codecov/codecov-action@v4
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          file: ./coverage.xml
+          fail_ci_if_error: true
+
+  security:
+    name: Security Checks
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: 'pip'
+
+      - name: Install security tools
         run: |
-          poetry run flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
-          poetry run flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
-      - name: Test with pytest
+          python -m pip install safety
+
+      - name: Run safety check
         run: |
-          poetry run pytest --cov
-      - name: Upload results to Codecov
-        uses: codecov/codecov-action@v4
+          safety check
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: python
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
         with:
-          token: ${{ secrets.CODECOV_TOKEN }}
+          category: "/language:python"

.gitignore

@@ -7,21 +7,28 @@ __pycache__/
 dist/
 build/
 *.egg-info/
+MANIFEST
 
 # C extensions
 *.so
 
-# Distribution / packaging
+# Virtual environment
 .Python
 env/
 venv/
 ENV/
+.env/
+.venv/
 env.bak/
 venv.bak/
+pythonenv*
+.python-version
+
+# Package files
 *.egg
+*.whl
 
 # PyInstaller
-#  Usually these files are written by a python script from a .spec file
 *.manifest
 *.spec
 
@@ -30,56 +37,99 @@ pip-log.txt
 pip-delete-this-directory.txt
 
 # Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
 .coverage
+.coverage.*
 coverage.xml
 *.cover
 *.py,cover
+.pytest_cache/
 nosetests.xml
 test_*.xml
-*.tox/
-*.nox/
-*.coverage
-*.hypothesis/
-*.pytest_cache/
-
-# Pytest
-.cache
+.hypothesis/
+
+# Translations
+*.mo
+*.pot
+
+# Django
 *.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
 
-# mypy
-.mypy_cache/
-.dmypy.json
-dmypy.json
+# Flask
+instance/
+.webassets-cache
 
-# IDEs and editors
-.vscode/
-.idea/
-*.swp
-*.swo
+# Scrapy
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+doc/_build/
+
+# PyBuilder
+target/
 
 # Jupyter Notebook
 .ipynb_checkpoints
+*.ipynb
 
-# Pyre type checker
-.pyre/
+# IPython
+profile_default/
+ipython_config.py
 
-# Virtual environment
-.venv/
+# pyenv
+
+# Celery
+celerybeat-schedule
+celerybeat.pid
 
+# SageMath
+*.sage.py
 
-# Environment variables
+# Environments
 .env
 .env.*
+.venv
 
-# macOS
-.DS_Store
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre
+.pyre/
 
-# Windows
+# pytype
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE settings
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS generated files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
 Thumbs.db
 Desktop.ini
 
-# Miscellaneous
-*.orig
-*.bak
-*.tmp
-/main.py
+# Project specific
+logs/
+tmp/
+temp/
+
+main.py

CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2024-01-10
+
+### Added
+
+- New asynchronous client `AsyncOutlineClient` using `aiohttp`
+- Comprehensive type hints and overloads for better IDE support
+- New methods for server management:
+    - `rename_server()` - Change server name
+    - `set_hostname()` - Configure server hostname
+    - `get_metrics_status()` - Check metrics collection status
+    - `set_metrics_status()` - Enable/disable metrics collection
+- Support for different metrics periods (DAILY, WEEKLY, MONTHLY)
+- Extended options for access key creation (method, encryption settings)
+- Improved error handling with detailed error messages
+- Context manager support with async `__aenter__` and `__aexit__`
+
+### Changed
+
+- Complete rewrite of the client to support asynchronous operations
+- Enhanced error hierarchy with `OutlineError` base class
+- Improved request handling with automatic session management
+- More flexible SSL/TLS certificate verification
+- Better JSON response parsing and validation
+- Updated type annotations to use modern Python typing features
+
+### Removed
+
+- Synchronous client implementation (migrated to async)
+- Direct requests-based HTTP handling
+
+## [0.1.2] - 2024-01-09
+
+### Added
+
+- Initial release with synchronous client
+- Basic Outline VPN server management features:
+    - Server information retrieval
+    - Access key management (create, list, delete)
+    - Data limit management
+    - Server port configuration
+    - Basic metrics retrieval
+- Pydantic models for data validation
+- Support for custom certificate verification
+- Optional JSON response format
+
+[0.2.0]: https://github.com/username/repo/compare/v0.1.2...v0.2.0
+
+[0.1.2]: https://github.com/username/repo/releases/tag/v0.1.2