The National Archives: Find Case Law

This repository is part of the Find Case Law project at The National Archives. For more information on the project, check the documentation.

MarkLogic API Client

This is an API Client for connecting to Marklogic for The National Archive's Caselaw site.

This package is published on PyPI: https://pypi.org/project/ds-caselaw-marklogic-api-client/

Usage

You can find documentation of the client class and available methods here.

Testing

To run the test suite:

poetry install
poetry run pytest

MarkLogic integration tests live under tests/marklogic/ and are opt-in: the default poetry run pytest excludes them (-m 'not marklogic'). They replace the old standalone smoketest/ module and load a fixed corpus from marklogic_harness/fixtures/documents/ (URIs under test/… as well as smoketest/…) so CI does not depend on staging.

CI runs them in a dedicated job: it starts MarkLogic from nationalarchives/ds-caselaw-marklogic, runs gradle mlWaitTillReady mlDeploy mlReloadSchemas, then runs the harness (see .github/workflows/test.yml). The merge fixture tests require the compiled_url_slugs TDE view from the caselaw templates.

Tests must run as a user with the same roles as production, not admin (for example, TDE views such as documents.compiled_url_slugs are only visible to roles with read permission on the templates, and admin has none). script/create_marklogic_test_user creates one with the roles of caselaw-editor-ui from ds-caselaw-marklogic.

Local setup: you must create the test user before running the integration harness against Docker or another MarkLogic instance. This is required on every fresh instance (for example a new container or wiped data); the harness rejects admin. Set MARKLOGIC_HOST, MARKLOGIC_USER, and MARKLOGIC_PASSWORD in a .env file, then:

MARKLOGIC_USER=caselaw-api-client-test MARKLOGIC_PASSWORD=... script/create_marklogic_test_user ../ds-caselaw-marklogic
poetry run pytest -o addopts= -p marklogic_harness.pytest_plugin -m marklogic tests/marklogic

Making changes

When making a change, update the changelog using the Keep a Changelog 1.0.0 format. Pull requests should not be merged before any relevant updates are made.

Deployment

This repository will auto-deploy documentation to GitHub Pages when changes are made to main.

Release process

When making a new release, update the changelog in the release pull request.

The package will only be released to PyPI if the branch is tagged. A merge to main alone will not trigger a release to PyPI.

To create a release:

0. Update the version number in pyproject.toml
1. Create a branch release/v{major}.{minor}.{patch}
2. Update CHANGELOG.md for the release
3. Commit and push
4. Open a PR from that branch to main
5. Get approval on the PR
6. Merge the PR to main and push
7. Tag the merge commit on main with v{major}.{minor}.{patch} and push the tag
8. Create a release in Github releases using the created tag

If the release fails to push to PyPI, you can delete the tag with git pull, git push --delete origin v1.2.3 and try again.