Skip to content

Commit 2f3e88b

Browse files
docs: Continue docstring harmonization to NumPy style (batch 4)
Harmonized modules: - gc.py - Garbage collection for external storage - migrate.py - Schema migration utilities - lineage.py - Attribute lineage management - objectref.py - ObjectRef class for fetched objects - content_registry.py - Content-addressed storage - admin.py - Database connection management Converted from Google/Sphinx style to NumPy style docstrings. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <[email protected]>
1 parent 8dbe50f commit 2f3e88b

File tree

6 files changed

+550
-298
lines changed

6 files changed

+550
-298
lines changed

src/datajoint/admin.py

Lines changed: 36 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,18 +9,24 @@
99

1010
def kill(restriction=None, connection=None, order_by=None):
1111
"""
12-
view and kill database connections.
13-
14-
:param restriction: restriction to be applied to processlist
15-
:param connection: a datajoint.Connection object. Default calls datajoint.conn()
16-
:param order_by: order by a single attribute or the list of attributes. defaults to 'id'.
17-
18-
Restrictions are specified as strings and can involve any of the attributes of
19-
information_schema.processlist: ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
20-
21-
Examples:
22-
dj.kill('HOST LIKE "%compute%"') lists only connections from hosts containing "compute".
23-
dj.kill('TIME > 600') lists only connections in their current state for more than 10 minutes
12+
View and kill database connections interactively.
13+
14+
Displays a list of active connections and prompts for connections to kill.
15+
16+
Parameters
17+
----------
18+
restriction : str, optional
19+
SQL WHERE clause to filter connections. Can use any attribute from
20+
information_schema.processlist: ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
21+
connection : Connection, optional
22+
A datajoint.Connection object. Defaults to datajoint.conn().
23+
order_by : str or list[str], optional
24+
Attribute(s) to order results by. Defaults to 'id'.
25+
26+
Examples
27+
--------
28+
>>> dj.kill('HOST LIKE "%compute%"') # List connections from hosts containing "compute"
29+
>>> dj.kill('TIME > 600') # List connections idle for more than 10 minutes
2430
"""
2531

2632
if connection is None:
@@ -61,16 +67,24 @@ def kill(restriction=None, connection=None, order_by=None):
6167

6268
def kill_quick(restriction=None, connection=None):
6369
"""
64-
Kill database connections without prompting. Returns number of terminated connections.
65-
66-
:param restriction: restriction to be applied to processlist
67-
:param connection: a datajoint.Connection object. Default calls datajoint.conn()
68-
69-
Restrictions are specified as strings and can involve any of the attributes of
70-
information_schema.processlist: ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
71-
72-
Examples:
73-
dj.kill('HOST LIKE "%compute%"') terminates connections from hosts containing "compute".
70+
Kill database connections without prompting.
71+
72+
Parameters
73+
----------
74+
restriction : str, optional
75+
SQL WHERE clause to filter connections. Can use any attribute from
76+
information_schema.processlist: ID, USER, HOST, DB, COMMAND, TIME, STATE, INFO.
77+
connection : Connection, optional
78+
A datajoint.Connection object. Defaults to datajoint.conn().
79+
80+
Returns
81+
-------
82+
int
83+
Number of terminated connections.
84+
85+
Examples
86+
--------
87+
>>> dj.kill_quick('HOST LIKE "%compute%"') # Kill connections from hosts with "compute"
7488
"""
7589
if connection is None:
7690
connection = conn()

src/datajoint/content_registry.py

Lines changed: 89 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -23,11 +23,15 @@ def compute_content_hash(data: bytes) -> str:
2323
"""
2424
Compute SHA256 hash of content.
2525
26-
Args:
27-
data: Content bytes
26+
Parameters
27+
----------
28+
data : bytes
29+
Content bytes.
2830
29-
Returns:
30-
Hex-encoded SHA256 hash (64 characters)
31+
Returns
32+
-------
33+
str
34+
Hex-encoded SHA256 hash (64 characters).
3135
"""
3236
return hashlib.sha256(data).hexdigest()
3337

@@ -39,11 +43,15 @@ def build_content_path(content_hash: str) -> str:
3943
Content is stored in a hierarchical structure to avoid too many files
4044
in a single directory: _content/{hash[:2]}/{hash[2:4]}/{hash}
4145
42-
Args:
43-
content_hash: SHA256 hex hash (64 characters)
46+
Parameters
47+
----------
48+
content_hash : str
49+
SHA256 hex hash (64 characters).
4450
45-
Returns:
46-
Relative path within the store
51+
Returns
52+
-------
53+
str
54+
Relative path within the store.
4755
"""
4856
if len(content_hash) != 64:
4957
raise DataJointError(f"Invalid content hash length: {len(content_hash)} (expected 64)")
@@ -54,12 +62,16 @@ def get_store_backend(store_name: str | None = None) -> StorageBackend:
5462
"""
5563
Get a StorageBackend for content storage.
5664
57-
Args:
58-
store_name: Name of the store to use. If None, uses the default object storage
59-
configuration or the configured default_store.
65+
Parameters
66+
----------
67+
store_name : str, optional
68+
Name of the store to use. If None, uses the default object storage
69+
configuration or the configured default_store.
6070
61-
Returns:
62-
StorageBackend instance
71+
Returns
72+
-------
73+
StorageBackend
74+
StorageBackend instance.
6375
"""
6476
# If store_name is None, check for configured default_store
6577
if store_name is None and config.object_storage.default_store:
@@ -77,12 +89,17 @@ def put_content(data: bytes, store_name: str | None = None) -> dict[str, Any]:
7789
If the content already exists (same hash), it is not re-uploaded.
7890
Returns metadata including the hash, store, and size.
7991
80-
Args:
81-
data: Content bytes to store
82-
store_name: Name of the store. If None, uses default store.
92+
Parameters
93+
----------
94+
data : bytes
95+
Content bytes to store.
96+
store_name : str, optional
97+
Name of the store. If None, uses default store.
8398
84-
Returns:
85-
Metadata dict with keys: hash, store, size
99+
Returns
100+
-------
101+
dict[str, Any]
102+
Metadata dict with keys: hash, store, size.
86103
"""
87104
content_hash = compute_content_hash(data)
88105
path = build_content_path(content_hash)
@@ -107,16 +124,24 @@ def get_content(content_hash: str, store_name: str | None = None) -> bytes:
107124
"""
108125
Retrieve content by its hash.
109126
110-
Args:
111-
content_hash: SHA256 hex hash of the content
112-
store_name: Name of the store. If None, uses default store.
113-
114-
Returns:
115-
Content bytes
116-
117-
Raises:
118-
MissingExternalFile: If content is not found
119-
DataJointError: If hash verification fails
127+
Parameters
128+
----------
129+
content_hash : str
130+
SHA256 hex hash of the content.
131+
store_name : str, optional
132+
Name of the store. If None, uses default store.
133+
134+
Returns
135+
-------
136+
bytes
137+
Content bytes.
138+
139+
Raises
140+
------
141+
MissingExternalFile
142+
If content is not found.
143+
DataJointError
144+
If hash verification fails.
120145
"""
121146
path = build_content_path(content_hash)
122147
backend = get_store_backend(store_name)
@@ -135,12 +160,17 @@ def content_exists(content_hash: str, store_name: str | None = None) -> bool:
135160
"""
136161
Check if content exists in storage.
137162
138-
Args:
139-
content_hash: SHA256 hex hash of the content
140-
store_name: Name of the store. If None, uses default store.
163+
Parameters
164+
----------
165+
content_hash : str
166+
SHA256 hex hash of the content.
167+
store_name : str, optional
168+
Name of the store. If None, uses default store.
141169
142-
Returns:
143-
True if content exists
170+
Returns
171+
-------
172+
bool
173+
True if content exists.
144174
"""
145175
path = build_content_path(content_hash)
146176
backend = get_store_backend(store_name)
@@ -151,15 +181,24 @@ def delete_content(content_hash: str, store_name: str | None = None) -> bool:
151181
"""
152182
Delete content from storage.
153183
154-
WARNING: This should only be called after verifying no references exist.
184+
This should only be called after verifying no references exist.
155185
Use garbage collection to safely remove unreferenced content.
156186
157-
Args:
158-
content_hash: SHA256 hex hash of the content
159-
store_name: Name of the store. If None, uses default store.
187+
Parameters
188+
----------
189+
content_hash : str
190+
SHA256 hex hash of the content.
191+
store_name : str, optional
192+
Name of the store. If None, uses default store.
160193
161-
Returns:
162-
True if content was deleted, False if it didn't exist
194+
Returns
195+
-------
196+
bool
197+
True if content was deleted, False if it didn't exist.
198+
199+
Warnings
200+
--------
201+
This permanently deletes content. Ensure no references exist first.
163202
"""
164203
path = build_content_path(content_hash)
165204
backend = get_store_backend(store_name)
@@ -175,12 +214,17 @@ def get_content_size(content_hash: str, store_name: str | None = None) -> int:
175214
"""
176215
Get the size of stored content.
177216
178-
Args:
179-
content_hash: SHA256 hex hash of the content
180-
store_name: Name of the store. If None, uses default store.
181-
182-
Returns:
183-
Size in bytes
217+
Parameters
218+
----------
219+
content_hash : str
220+
SHA256 hex hash of the content.
221+
store_name : str, optional
222+
Name of the store. If None, uses default store.
223+
224+
Returns
225+
-------
226+
int
227+
Size in bytes.
184228
"""
185229
path = build_content_path(content_hash)
186230
backend = get_store_backend(store_name)

0 commit comments

Comments
 (0)