Open source Deepnote Toolkit

Author: m1so

.codecov.yml

@@ -0,0 +1,10 @@
+coverage:
+  status:
+    project:
+      default:
+        target: auto
+        threshold: 0.05%
+    patch:
+      default:
+        target: auto
+        threshold: 0.05%

.cursorrules

@@ -0,0 +1,170 @@
+# Deepnote Toolkit - .cursorrules
+
+## Role and Expertise
+
+You are an expert Python developer working on the Deepnote Toolkit, a Python package for Deepnote environment integration. Your code should be clean, efficient, and follow the project's established patterns for Jupyter/IPython integration.
+
+## Coding Standards
+
+### General Principles
+
+- Write clean, readable Python code
+- Follow PEP 8 style guide
+- Use type hints where appropriate
+- Document functions and classes with docstrings
+- Use f-strings instead of .format() for string formatting
+- Use pathlib.Path for file path operations instead of os.path
+
+### Type Hints
+
+- Always use `Optional[T]` for parameters that can be None (not `T = None`)
+- Use explicit type hints for function parameters and return values
+- Example: `def function(param: Optional[str] = None) -> str:`
+
+### Project-Specific Standards
+
+- Maximum line length: 88 characters (Black default)
+- Use black for code formatting
+- Use isort for import sorting (black profile)
+- Use flake8 for linting
+
+### Code Patterns
+
+- Early returns to reduce nesting: Check conditions and return early
+- Extract common checks into variables for readability
+- Use dictionary unpacking for headers: `headers = {"Content-Type": "application/json", **auth_headers}`
+- CLI arguments: Use space-separated format (`--port 8080`)
+
+### Naming Conventions
+
+- **Variables and Functions**: snake_case
+- **Classes**: PascalCase
+- **Files**: snake_case
+- **Test Files**: test\_\*.py
+
+### Error Handling
+
+- Use appropriate exception types
+- Log errors with context
+- Handle Jupyter/IPython specific exceptions properly
+
+## Project Structure
+
+Organize the project with clear separation:
+
+- **deepnote_toolkit /**: Core package code
+- **tests/**: Unit and integration tests
+- **configs/**: Configuration files
+- **dockerfiles/**: Docker environment definitions
+- **bin/**: Shell scripts and utilities
+
+## Dependencies Management
+
+### Poetry Groups
+
+- **Core Dependencies**: `tool.poetry.dependencies`
+  ```bash
+  poetry add <package>
+  ```
+- **Server Dependencies**: `tool.poetry.group.server.dependencies`
+  ```bash
+  poetry add --group server <package>
+  ```
+- **Development Dependencies**: `tool.poetry.group.dev.dependencies`
+  ```bash
+  poetry add --group dev <package>
+  ```
+
+## Testing Standards
+
+### Environment Variables
+
+Required for all tests:
+
+- TEST_TYPE
+- TOOLKIT_VERSION
+
+Additional for integration tests:
+
+- TOOLKIT_INDEX_URL
+
+### Commands
+
+```bash
+# Run local tests
+./bin/test-local
+
+# Run specific test type
+export TEST_TYPE="unit|integration"
+export TOOLKIT_VERSION="local-build"
+./bin/test
+```
+
+## Docker Environments
+
+Available Dockerfiles:
+
+- builder.Dockerfile: Creates bundles
+- test.Dockerfile: Testing environment
+- jupyter-for-local.Dockerfile: Local development
+
+## Security Requirements
+
+### Public Repository Rules
+
+- No secrets or sensitive information in codebase
+- No internal URLs or credentials
+- No customer data
+
+### Pre-commit Hooks
+
+Setup: `poetry poe setup-hooks`
+
+Required hooks:
+
+- trailing-whitespace
+- end-of-file-fixer
+- check-yaml
+- check-added-large-files
+- flake8
+- isort
+
+## Python Version Support
+
+Supported versions:
+
+- Python 3.9
+- Python 3.10
+- Python 3.11
+- Python 3.12
+
+## Code Examples
+
+### Example Activity Pattern
+
+```python
+def configure_dataframe_formatter(spec):
+    """Configure the DataFrame formatter with given specifications.
+
+    Args:
+        spec: Formatting specifications for DataFrame display
+    """
+    global df_formatter_spec
+    df_formatter_spec = spec
+```
+
+### Example Test Pattern
+
+```python
+class TestDataFrameUtils(unittest.TestCase):
+    def setUp(self):
+        self.df = pd.DataFrame({
+            "col1": [1, 2, 3],
+            "col2": [4, 5, 6]
+        })
+
+    def test_browse_dataframe(self):
+        """Test DataFrame browsing functionality."""
+        result = browse_dataframe(self.df, {"view": "table"})
+        self.assertIsInstance(result, pd.DataFrame)
+```

.flake8

@@ -0,0 +1,9 @@
+[flake8]
+max-line-length = 100
+# This tells flake8 to only select error codes that start with E (PEP8 errors) and F (PyFlakes errors). It excludes warnings (W) and complexity checks (C).
+select = E,F
+extend-ignore = E203, E266, E501, W503
+exclude = .git,__pycache__,.nox,docs/source/conf.py,old,build,dist,configs/ipython/profile_default/ipython_config.py,.venv,.poetry
+per-file-ignores =
+    # imported but unused
+    __init__.py: F401

.github/actions/build-wheel/action.yml

@@ -0,0 +1,57 @@
+name: 'Build Python Wheel'
+description: 'Build a Python wheel package using Poetry with dynamic versioning'
+
+outputs:
+  wheel-name:
+    description: 'Name of the built wheel file'
+    value: ${{ steps.build.outputs.wheel-name }}
+  version:
+    description: 'Package version'
+    value: ${{ steps.build.outputs.version }}
+  wheel-path:
+    description: 'Full path to the wheel file'
+    value: ${{ steps.build.outputs.wheel-path }}
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Build wheel and extract metadata
+      id: build
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        # Ensure dynamic versioning plugin is installed
+        poetry self add 'poetry-dynamic-versioning[plugin]>=1.4.0' 2>/dev/null || true
+
+        # Remove any pre-existing artifacts to avoid publishing stale wheels
+        rm -rf dist
+        mkdir -p dist
+
+        # Build the wheel
+        echo "Building wheel with Poetry..."
+        poetry build --format wheel
+
+        # Get version and wheel info
+        VERSION=$(poetry version --short)
+        WHEEL_COUNT=$(find dist -maxdepth 1 -name '*.whl' | wc -l | tr -d ' ')
+        if [ "$WHEEL_COUNT" -ne 1 ]; then
+          echo "ERROR: Expected exactly 1 wheel, found ${WHEEL_COUNT}"
+          ls -la dist/
+          exit 1
+        fi
+        WHEEL=$(find dist -maxdepth 1 -name '*.whl' -print -quit)
+        WHEEL_NAME=$(basename "$WHEEL")
+        WHEEL_PATH=$(realpath "$WHEEL")
+
+        # Output to GitHub Actions
+        {
+          echo "wheel-name=${WHEEL_NAME}"
+          echo "version=${VERSION}"
+          echo "wheel-path=${WHEEL_PATH}"
+        } >> "$GITHUB_OUTPUT"
+
+        # Display results
+        echo "✓ Built wheel: $WHEEL_NAME"
+        echo "✓ Version: $VERSION"
+        echo "✓ Path: $WHEEL_PATH"

.github/actions/export-version/action.yml

@@ -0,0 +1,21 @@
+name: 'Export Version'
+description: 'Exports VERSION environment variable based on git ref'
+outputs:
+  version:
+    description: 'The version string'
+    value: ${{ steps.export-version.outputs.version }}
+runs:
+  using: 'composite'
+  steps:
+    - name: Create VERSION env variable
+      id: export-version
+      shell: bash
+      run: |
+        if [[ -n "$GITHUB_REF_NAME" && "$GITHUB_REF_TYPE" == "tag" ]]; then
+          VERSION=$GITHUB_REF_NAME
+        else
+          VERSION="$(git rev-parse --short HEAD)"
+        fi
+        echo "VERSION=$VERSION" >> $GITHUB_ENV
+        echo "version=$VERSION" >> $GITHUB_OUTPUT
+        echo "Version is set to: $VERSION"