Merge branch 'main' into support-for-prefixes

Author: hoijnet

.gitignore

@@ -40,6 +40,7 @@ terminusdb_client_coverage/
 *~
 
 venv/
+.venv/
 
 # due to using tox and pytest
 .tox

CONTRIBUTING.md

@@ -44,40 +44,59 @@ That's it! You're now ready to start contributing. See [Poetry Scripts Reference
 
 ## Setting up dev environment 💻
 
-Make sure you have Python>=3.9 installed. We use [Poetry](https://python-poetry.org/) for dependency management.
+Make sure you have Python>=3.9 and <3.13 installed.
 
-### Using Poetry (Recommended)
+[Fork and clone](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) this repo, then set up your development environment using one of the methods below.
 
-1. [Fork and clone](https://help.github.com/en/github/getting-started-with-github/fork-a-repo) this repo
+### Option 1: Using venv (recommended)
 
-2. Create and activate a virtual environment:
-   ```bash
-   python3 -m venv .venv
-   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
-   ```
+Create and activate a virtual environment:
 
-3. Install Poetry and dependencies:
-   ```bash
-   pip install poetry
-   poetry install --with dev
-   ```
+```bash
+# Create venv with Python 3.12 (or any version 3.9-3.12)
+python3.12 -m venv .venv
 
-4. Install the package in editable mode:
-   ```bash
-   poetry run dev install-dev
-   ```
+# Activate the virtual environment
+source .venv/bin/activate  # On macOS/Linux
+# .venv\Scripts\activate   # On Windows
 
-5. Start TerminusDB server (required for integration tests):
-   ```bash
-   docker run --pull always -d -p 127.0.0.1:6363:6363 -v terminusdb_storage:/app/terminusdb/storage --name terminusdb terminusdb/terminusdb-server:v12
-   ```
-   
-   To stop the server when done:
+# Install the package in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Install pytest for running tests
+pip install pytest
+```
+
+### Option 2: Using pipenv
+
+We also support [pipenv](https://pipenv-fork.readthedocs.io/en/latest/) for dev environment:
+
+```bash
+pip install pipenv --upgrade
+pipenv install --dev --pre
+```
+
+Or simply run `make init`.
+
+To "editable" install the local Terminus Client Python:
+
+`pip install -e .`
+
+### Running a local TerminusDB server
+
+**To run integration tests, you need either Docker or a local TerminusDB server.**
+
+For integration tests, you can either:
+
+1. **Use Docker** (automatic): Tests will automatically start a Docker container if no server is detected
+2. **Use a local server**: Start the TerminusDB test server from the main terminusdb repository:
    ```bash
-   docker stop terminusdb
-   docker rm terminusdb
+   cd /path/to/terminusdb
+   ./tests/terminusdb-test-server.sh start
    ```
 
+The test configuration will automatically detect and use an available server.
+
 **To run integration tests, Docker must be installed locally.**
 
 We use [shed](https://pypi.org/project/shed/) to lint our code. You can run it manually with `poetry run dev lint`, or set up a pre-commit hook (requires Python 3.10+):

terminusdb_client/client/Client.py

@@ -563,6 +563,108 @@ def get_commit_history(self, max_history: int = 500) -> list:
             raise ValueError("max_history needs to be non-negative.")
         return self.log(count=max_history)
 
+    def get_document_history(
+        self,
+        doc_id: str,
+        team: Optional[str] = None,
+        db: Optional[str] = None,
+        start: int = 0,
+        count: int = 10,
+        created: bool = False,
+        updated: bool = False,
+    ) -> list:
+        """Get the commit history for a specific document
+
+        Returns the history of changes made to a document, ordered backwards
+        in time from the most recent change. Only commits where the specified
+        document was created, modified, or deleted are included.
+
+        Parameters
+        ----------
+        doc_id : str
+            The document ID (IRI) to retrieve history for (e.g., "Person/alice")
+        team : str, optional
+            The team from which the database is. Defaults to the class property.
+        db : str, optional
+            The database. Defaults to the class property.
+        start : int, optional
+            Starting index for pagination. Defaults to 0.
+        count : int, optional
+            Maximum number of history entries to return. Defaults to 10.
+        created : bool, optional
+            If True, return only the creation time. Defaults to False.
+        updated : bool, optional
+            If True, return only the last update time. Defaults to False.
+
+        Raises
+        ------
+        InterfaceError
+            If the client is not connected to a database
+        DatabaseError
+            If the API request fails or document is not found
+
+        Returns
+        -------
+        list
+            List of history entry dictionaries containing commit information
+            for the specified document:
+            ```
+            [
+              {
+                "author": "admin",
+                "identifier": "tbn15yq6rw1l4e9bgboyu3vwcoxgri5",
+                "message": "Updated document",
+                "timestamp": datetime.datetime(2023, 4, 6, 19, 1, 14, 324928)
+              },
+              {
+                "author": "admin",
+                "identifier": "3v3naa8jrt8612dg5zryu4vjqwa2w9s",
+                "message": "Created document",
+                "timestamp": datetime.datetime(2023, 4, 6, 19, 0, 47, 406387)
+              }
+            ]
+            ```
+
+        Example
+        -------
+        >>> from terminusdb_client import Client
+        >>> client = Client("http://127.0.0.1:6363")
+        >>> client.connect(db="example_db")
+        >>> history = client.get_document_history("Person/Jane")
+        >>> print(f"Document modified {len(history)} times")
+        >>> print(f"Last change by: {history[0]['author']}")
+        """
+        self._check_connection(check_db=(not team or not db))
+        team = team if team else self.team
+        db = db if db else self.db
+
+        params = {
+            'id': doc_id,
+            'start': start,
+            'count': count,
+        }
+        if created:
+            params['created'] = created
+        if updated:
+            params['updated'] = updated
+
+        result = self._session.get(
+            f"{self.api}/history/{team}/{db}",
+            params=params,
+            headers=self._default_headers,
+            auth=self._auth(),
+        )
+
+        history = json.loads(_finish_response(result))
+
+        # Post-process timestamps from Unix timestamp to datetime objects
+        if isinstance(history, list):
+            for entry in history:
+                if 'timestamp' in entry and isinstance(entry['timestamp'], (int, float)):
+                    entry['timestamp'] = datetime.fromtimestamp(entry['timestamp'])
+
+        return history
+
     def _get_current_commit(self):
         descriptor = self.db
         if self.branch:

terminusdb_client/tests/integration_tests/conftest.py

@@ -13,7 +13,8 @@ def is_local_server_running():
     """Check if local TerminusDB server is running at http://127.0.0.1:6363"""
     try:
         response = requests.get("http://127.0.0.1:6363", timeout=2)
-        # Server responds with 404 for root path, which means it's running
+        # Server responds with 200 (success) or 404 (not found but server is up)
+        # 401 (unauthorized) also indicates server is running but needs auth
         return response.status_code in [200, 404]
     except (requests.exceptions.ConnectionError, requests.exceptions.Timeout):
         return False
@@ -73,7 +74,9 @@ def docker_url_jwt(pytestconfig):
 
     # Check if JWT server is already running (port 6367)
     if is_jwt_server_running():
-        print("\n✓ Using existing JWT Docker TerminusDB server at http://127.0.0.1:6367")
+        print(
+            "\n✓ Using existing JWT Docker TerminusDB server at http://127.0.0.1:6367"
+        )
         yield ("http://127.0.0.1:6367", jwt_token)
         return  # Don't clean up - server was already running
 
@@ -128,7 +131,9 @@ def docker_url_jwt(pytestconfig):
 
         if seconds_waited > MAX_CONTAINER_STARTUP_TIME:
             clean_up_container()
-            raise RuntimeError(f"JWT Container was too slow to startup (waited {MAX_CONTAINER_STARTUP_TIME}s)")
+            raise RuntimeError(
+                f"JWT Container was too slow to startup (waited {MAX_CONTAINER_STARTUP_TIME}s)"
+            )
 
     yield (test_url, jwt_token)
     clean_up_container()
@@ -145,9 +150,15 @@ def docker_url(pytestconfig):
     """
     # Check if local test server is already running (port 6363)
     if is_local_server_running():
-        print("\n✓ Using existing local TerminusDB test server at http://127.0.0.1:6363")
-        print("⚠️  WARNING: Local server should be started with TERMINUSDB_AUTOLOGIN=true")
-        print("   Or use: TERMINUSDB_SERVER_AUTOLOGIN=true ./tests/terminusdb-test-server.sh restart")
+        print(
+            "\n✓ Using existing local TerminusDB test server at http://127.0.0.1:6363"
+        )
+        print(
+            "⚠️  WARNING: Local server should be started with TERMINUSDB_AUTOLOGIN=true"
+        )
+        print(
+            "   Or use: TERMINUSDB_SERVER_AUTOLOGIN=true ./tests/terminusdb-test-server.sh restart"
+        )
         yield "http://127.0.0.1:6363"
         return  # Don't clean up - server was already running
 
@@ -200,7 +211,9 @@ def docker_url(pytestconfig):
                 response = requests.get(test_url)
                 # Server responds with 404 for root path, which means it's running
                 assert response.status_code in [200, 404]
-                print(f"✓ Docker container started successfully after {seconds_waited}s")
+                print(
+                    f"✓ Docker container started successfully after {seconds_waited}s"
+                )
                 break
             except (requests.exceptions.ConnectionError, AssertionError):
                 pass
@@ -210,7 +223,9 @@ def docker_url(pytestconfig):
 
         if seconds_waited > MAX_CONTAINER_STARTUP_TIME:
             clean_up_container()
-            raise RuntimeError(f"Container was too slow to startup (waited {MAX_CONTAINER_STARTUP_TIME}s)")
+            raise RuntimeError(
+                f"Container was too slow to startup (waited {MAX_CONTAINER_STARTUP_TIME}s)"
+            )
 
     yield test_url
     clean_up_container()

terminusdb_client/tests/integration_tests/test_client.py

@@ -211,6 +211,70 @@ def test_log(docker_url):
     assert log[0]['@type'] == 'InitialCommit'
 
 
+def test_get_document_history(docker_url):
+    # Create client
+    client = Client(docker_url, user_agent=test_user_agent)
+    client.connect()
+
+    # Create test database
+    db_name = "testDB" + str(random())
+    client.create_database(db_name, team="admin")
+    client.connect(db=db_name)
+
+    # Add a schema
+    schema = {
+        "@type": "Class",
+        "@id": "Person",
+        "name": "xsd:string",
+        "age": "xsd:integer"
+    }
+    client.insert_document(schema, graph_type=GraphType.SCHEMA)
+
+    # Insert a document
+    person = {"@type": "Person", "@id": "Person/Jane", "name": "Jane", "age": 30}
+    client.insert_document(person, commit_msg="Created Person/Jane")
+
+    # Update the document to create history
+    person["name"] = "Jane Doe"
+    person["age"] = 31
+    client.update_document(person, commit_msg="Updated Person/Jane name and age")
+
+    # Update again
+    person["age"] = 32
+    client.update_document(person, commit_msg="Updated Person/Jane age")
+
+    # Get document history
+    history = client.get_document_history("Person/Jane")
+
+    # Assertions
+    assert isinstance(history, list)
+    assert len(history) >= 3  # At least insert and two updates
+    assert all('timestamp' in entry for entry in history)
+    assert all(isinstance(entry['timestamp'], dt.datetime) for entry in history)
+    assert all('author' in entry for entry in history)
+    assert all('message' in entry for entry in history)
+    assert all('identifier' in entry for entry in history)
+
+    # Verify messages are in the history (order may vary)
+    messages = [entry['message'] for entry in history]
+    assert "Created Person/Jane" in messages
+    assert "Updated Person/Jane name and age" in messages
+    assert "Updated Person/Jane age" in messages
+
+    # Test with pagination
+    paginated_history = client.get_document_history("Person/Jane", start=0, count=2)
+    assert len(paginated_history) == 2
+
+    # Test with team/db override
+    history_override = client.get_document_history(
+        "Person/Jane", team="admin", db=db_name
+    )
+    assert len(history_override) == len(history)
+
+    # Cleanup
+    client.delete_database(db_name, "admin")
+
+
 def test_get_triples(docker_url):
     client = Client(docker_url, user_agent=test_user_agent, team="admin")
     client.connect()