diff --git a/AGENTS.md b/AGENTS.md new file mode 120000 index 0000000..681311e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1 @@ +CLAUDE.md \ No newline at end of file diff --git a/CLAUDE.md b/CLAUDE.md index 23a328c..80cf275 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,77 +1,27 @@ -# Deepnote Toolkit - Guidelines for Claude - -## Build, Lint & Test Commands - -- Build: `./bin/build` -- Format: `poetry run black .` -- Lint: `poetry run flake8 .` -- Sort imports: `poetry run isort .` -- Setup pre-commit hooks: `poetry poe setup-hooks` -- Run unit tests (all): `nox -e unit` -- Run integration tests: `nox -e integration` -- Run specific test: `nox --force-color -e unit -p 3.10 -- tests/unit/test_file.py::TestClass::test_name` -- Run local tests: `./bin/test-local` - -## Code Coverage Commands - -- Run tests with coverage: `./bin/test-local` (coverage enabled by default) -- Run without coverage: `COVERAGE_ENABLED=false ./bin/test-local` -- Combine coverage files: `poetry run coverage combine` -- Generate coverage report: `poetry run coverage report` -- Check coverage threshold: `poetry run coverage report --fail-under=55` -- Generate HTML report: `poetry run coverage html` -- Generate XML report: `poetry run coverage xml` -- Generate JSON report: `poetry run coverage json` - -## Code Style Guidelines - -- Follow PEP 8 with Black formatting (line length: 88) -- Use isort with Black profile for import sorting -- Use type hints consistently -- Use docstrings for all functions/classes -- Use f-strings instead of .format() for string formatting -- Use pathlib.Path for file path operations instead of os.path - -## Type Hints and Imports - -- 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:` - -## Naming Conventions - -- Files/Functions/Variables: `snake_case` -- Classes: `PascalCase` -- Test files: `test_*.py` - -## Error Handling - -- Use appropriate exception types -- Log errors with context -- Handle Jupyter/IPython specific exceptions properly - -## Python Version Support - -- Python 3.10, 3.11, 3.12, 3.13 - -## Dependencies - -- Use Poetry for dependency management -- Core deps: `poetry add ` -- Dev deps: `poetry add --group dev ` -- Server deps: `poetry add --group server ` - -## 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`) - -## Testing - -You can run a single test using the following format: - -```sh -TEST_TYPE="unit" TOOLKIT_VERSION="local-build" ./bin/test tests/unit/test_sql_execution.py::TestExecuteSql::test_execute_sql_with_connection_json_with_snowflake_encrypted_private_key -``` +# Deepnote Toolkit + +This Python package provides the kernel, Jupyter, Streamlit, language-server, SQL, and runtime services used by Deepnote Cloud and local Deepnote clients. + +## Working rules + +- Use the routing table before searching. Start with the owning package, its tests, and the relevant developer or user documentation; do not traverse unrelated runtime components. +- Read `pyproject.toml`, `noxfile.py`, scripts, and CI for current Python support, dependencies, commands, and quality gates instead of copying them into guidance. +- Add or update focused unit or integration tests for behavior changes and run the narrowest relevant environment before broader checks. +- Follow existing typed Python patterns, use `pathlib.Path` for filesystem paths, and preserve contextual error handling at process and Jupyter boundaries. +- Document non-obvious coupling at every affected runtime component with reciprocal references. +- Put durable discoveries in shared documentation under `docs/`, not local memory files. Keep this file limited to behavior and routing. +- Never publish packages, promote runtime versions, or change a deployed environment without explicit user approval. + +## Routing table + +| When looking for | Look into | +| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | +| Toolkit purpose and user-facing capabilities | [README.md](README.md) | +| Development setup, local Cloud integration, and releases | [CONTRIBUTING.md](CONTRIBUTING.md) | +| Current dependencies, entry points, and tool configuration | `pyproject.toml`, `noxfile.py`, `bin/`, and `.github/workflows/` | +| Configuration implementation and extension points | [docs/dev/configuration.md](docs/dev/configuration.md) and the referenced modules | +| Public configuration behavior | [docs/user/configuration.md](docs/user/configuration.md) | +| TypeScript notebook schemas and local orchestration | [deepnote](https://github.com/deepnote/deepnote) (`../deepnote` when available) | +| Deepnote Cloud integration and consumers | [deepnote-internal](https://github.com/deepnote/deepnote-internal) (`../deepnote-internal` when available) | +| Editor-side server lifecycle and integrations | [vscode-deepnote](https://github.com/deepnote/vscode-deepnote) (`../vscode-deepnote` when available) | +| Deployed Toolkit versions and review apps | [app-config](https://github.com/deepnote/app-config) (`../app-config` when available) |