Deprecate the ~log table.. Improve code organization: docstrings, type hints, and imports. #1297

dimitri-yatsenko · 2025-12-25T04:26:52Z

Fix #1298 - Deprecate the ~log table.

Add module docstrings to cli.py, admin.py, logging.py, and hash.py
Add from __future__ import annotations for PEP 563 deferred evaluation
Modernize type hints using Python 3.10+ syntax (X | None instead of Optional[X])
Use TYPE_CHECKING imports to avoid circular dependencies
Improve function docstrings to Google style with Args/Returns sections
Add type annotations to:
- admin.py: set_password(), kill(), and kill_quick() functions
- cli.py: cli() function
- hash.py: all hashing functions
- logging.py: excepthook() function
- utils.py: all utility functions and ClassProperty

- Add module docstrings to cli.py, admin.py, logging.py, and hash.py - Add `from __future__ import annotations` for PEP 563 deferred evaluation - Modernize type hints using Python 3.10+ syntax (X | None instead of Optional[X]) - Use TYPE_CHECKING imports to avoid circular dependencies - Improve function docstrings to Google style with Args/Returns sections - Add type annotations to key public APIs in: - connection.py: Connection class and conn() function - fetch.py: Fetch and Fetch1 classes - expression.py: QueryExpression class properties and methods - utils.py: utility functions - hash.py: hashing functions - admin.py: kill() and kill_quick() functions

- Add module docstrings to cli.py, admin.py, logging.py, and hash.py - Add `from __future__ import annotations` for PEP 563 deferred evaluation - Modernize type hints using Python 3.10+ syntax (X | None instead of Optional[X]) - Use TYPE_CHECKING imports to avoid circular dependencies - Improve function docstrings to Google style with Args/Returns sections - Add type annotations to: - admin.py: set_password(), kill(), and kill_quick() functions - cli.py: cli() function - hash.py: all hashing functions - logging.py: excepthook() function - utils.py: all utility functions and ClassProperty Co-authored-by: dimitri-yatsenko <[email protected]>

…ew-code-organization-9135z Merges restructured project with src/datajoint/ layout and code organization improvements including docstrings, type hints, and modern Python 3.10+ features. Co-authored-by: dimitri-yatsenko <[email protected]>

Closes #1298 The ~log table is a client-side audit logging mechanism that has been superseded by modern alternatives including: - Server-side database audit logging - Infrastructure logging platforms (Datadog, CloudWatch) - Python's standard logging module Changes: - Remove Log class from table.py - Remove log property from Schema class - Replace self._log() calls with logger.info/debug - Remove special ~log handling from heading.py - Delete test_log.py Existing ~log tables in databases remain but will no longer be written to. All operations now emit through Python's logging module instead. Co-authored-by: dimitri-yatsenko <[email protected]>

The package was moved to src/datajoint/ but these files remained as orphans after the merge. Removing to avoid confusion. Co-authored-by: dimitri-yatsenko <[email protected]>

d-v-b · 2025-12-30T16:25:48Z

src/datajoint/utils.py

        self.f = f

-    def __get__(self, obj, owner):
+    def __get__(self, obj: Any, owner: type) -> Any:


object is generally a better type annotation than Any when working with unknown python objects. An annotation of object basically says "this could be any python object", whereas the annotation of Any says "don't do any type-checking against this value".

and why does this function take obj, despite not doing anything with it?

ClassProperty was introduced probably around Python 3.4 days and I wonder if it can be replaced altogether. Looking into it...

d-v-b · 2025-12-30T16:27:56Z

src/datajoint/utils.py


-def safe_copy(src, dest, overwrite=False):
+def safe_copy(
+    src: str | Path,


if str | Path is used a lot in the codebase, you might want to introduce a type alias in one place like PathLike = str | Path. This adds indirection however, which is a drawback.

d-v-b · 2025-12-30T16:29:10Z

src/datajoint/connection.py

+    *,
+    init_fun: str | None = None,
+    reset: bool = False,
+    use_tls: bool | dict[str, Any] | None = None,


dict[str, object] should be preferred over dict[str, Any]

d-v-b · 2025-12-30T16:29:28Z

src/datajoint/connection.py

        return self

-    def __next__(self):
+    def __next__(self) -> tuple | dict:


tuple and dict need type parameters

d-v-b · 2025-12-30T16:29:48Z

src/datajoint/connection.py

        return next(self._iter)

-    def fetchall(self):
+    def fetchall(self) -> list[tuple | dict]:


tuple and dict need type parameters

d-v-b · 2025-12-30T16:29:52Z

src/datajoint/connection.py

        return self._data

-    def fetchone(self):
+    def fetchone(self) -> tuple | dict:


tuple and dict need type parameters

d-v-b · 2025-12-30T16:30:25Z

src/datajoint/connection.py

        self._conn.close()

-    def register(self, schema):
+    def register(self, schema: Any) -> None:


is schema really Any?

d-v-b · 2025-12-30T16:31:59Z

src/datajoint/hash.py



-def key_hash(mapping):
+def key_hash(mapping: Mapping) -> str:


mapping needs type parameters

d-v-b · 2025-12-30T16:34:16Z

if you want a fancier logging solution, I like structlog a lot more than the standard python logging library. It's an extra dependency so only worth considering if you rely heavily on logging.

d-v-b

looks good, just some type annotations that require parameters (dict, list, Mapping) and a request to use object instead of Any as a catch-all type

github-actions bot added the enhancement Indicates new improvements label Dec 25, 2025

claude and others added 2 commits December 25, 2025 04:34

dimitri-yatsenko force-pushed the claude/review-code-organization-9135z branch from 90a1b71 to 4eb8202 Compare December 25, 2025 04:36

dimitri-yatsenko requested a review from d-v-b December 25, 2025 04:37

dimitri-yatsenko changed the title ~~Improve code organization: docstrings, type hints, and imports~~ Improve code organization: docstrings, type hints, and imports. Deprecate the ~log table. Dec 25, 2025

dimitri-yatsenko requested a review from mweitzel December 25, 2025 04:45

dimitri-yatsenko self-assigned this Dec 25, 2025

dimitri-yatsenko requested a review from ttngu207 December 25, 2025 04:46

Remove orphaned datajoint/ directory after src/ restructure

674d2ca

The package was moved to src/datajoint/ but these files remained as orphans after the merge. Removing to avoid confusion. Co-authored-by: dimitri-yatsenko <[email protected]>

dimitri-yatsenko changed the title ~~Improve code organization: docstrings, type hints, and imports. Deprecate the ~log table.~~ Deprecate the ~log table.. Improve code organization: docstrings, type hints, and imports. Dec 25, 2025

d-v-b reviewed Dec 30, 2025

View reviewed changes

src/datajoint/hash.py

def key_hash(mapping):

def key_hash(mapping: Mapping) -> str:

Copy link

Contributor

d-v-b Dec 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

mapping needs type parameters

d-v-b requested changes Dec 30, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Deprecate the ~log table.. Improve code organization: docstrings, type hints, and imports. #1297

Deprecate the ~log table.. Improve code organization: docstrings, type hints, and imports. #1297

Uh oh!

dimitri-yatsenko commented Dec 25, 2025 •

edited

Loading

Uh oh!

d-v-b Dec 30, 2025

Uh oh!

dimitri-yatsenko Dec 30, 2025

Uh oh!

d-v-b Dec 30, 2025

Uh oh!

d-v-b Dec 30, 2025

Uh oh!

d-v-b Dec 30, 2025 •

edited

Loading

Uh oh!

d-v-b Dec 30, 2025

Uh oh!

d-v-b Dec 30, 2025

Uh oh!

d-v-b Dec 30, 2025

Uh oh!

d-v-b Dec 30, 2025

Uh oh!

d-v-b commented Dec 30, 2025

Uh oh!

d-v-b left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants



		def key_hash(mapping):
		def key_hash(mapping: Mapping) -> str:

Deprecate the ~log table.. Improve code organization: docstrings, type hints, and imports. #1297

Are you sure you want to change the base?

Deprecate the ~log table.. Improve code organization: docstrings, type hints, and imports. #1297

Uh oh!

Conversation

dimitri-yatsenko commented Dec 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-v-b Dec 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-v-b commented Dec 30, 2025

Uh oh!

d-v-b left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

dimitri-yatsenko commented Dec 25, 2025 •

edited

Loading

d-v-b Dec 30, 2025 •

edited

Loading