albert 1.13.0b2__tar.gz → 1.14.1__tar.gz

albert-1.14.1/AGENTS.md

@@ -0,0 +1,163 @@
+# AGENTS
+
+This file is the single source of truth for coding-agent guidance in this repo.
+Follow these rules and patterns when making changes.
+
+## Rules
+
+### Changelog
+
+Any change that impacts SDK users must be added to the changelog under the
+appropriate release version, following Keep a Changelog 1.1.0.
+
+This includes breaking and non-breaking changes, such as API or naming changes,
+payload/behavior changes, deprecations, or internal refactors that affect
+user-visible behavior.
+
+When in doubt, add a changelog entry.
+
+### Using Numpy-Style Docstrings
+
+Any new public methods and classes in this repository should follow the
+Numpy-style docstring format. This ensures consistency and compatibility with
+mkdocstrings for automated documentation generation.
+
+Example:
+
+```python
+class Cas:
+    """
+    Represents a CAS entity.
+
+    Attributes
+    ----------
+    number : str
+        The CAS number.
+    name : str, optional
+        The name of the CAS.
+    """
+
+    def from_string(cls, *, number: str) -> "Cas":
+        """
+        Creates a Cas object from a string.
+
+        Parameters
+        ----------
+        number : str
+            The CAS number.
+
+        Returns
+        -------
+        Cas
+            The Cas object created from the string.
+        """
+        return cls(number=number)
+```
+
+When contributing new classes or methods, ensure all public members have
+properly formatted Numpy-style docstrings.
+
+## Design Principles
+
+1. **Keep it simple** - Avoid over-engineering. Make minimal changes. Don't create massive file diffs or edit unnecessary files. Validate at boundaries, trust internal code based on type hints.
+
+2. **Follow existing code patterns** - Check similar code in the codebase before writing new code. Match existing patterns rather than creating new ones.
+
+3. **YAGNI** - Only edit files absolutely necessary for the task. Don't add extra configuration unless explicitly needed. Prefer sensible defaults over configurable complexity.
+
+4. **Verify by running code** - When guessing about how something works, run the code and verify rather than assuming.
+
+5. Verify you haven't over-engineered the solution
+
+## Project Basics
+
+- Python: >=3.10 (type hints use modern syntax like list[str]).
+- Formatting and linting: Ruff (line length 99). CI and pre-commit enforce this.
+- Commit style: Conventional Commits (type(scope): summary), enforced by hooks.
+
+Useful commands:
+
+```bash
+./setup.sh
+uv run ruff format .
+uv run ruff check . --fix
+uv run pytest
+```
+
+## Repo Layout
+
+- src/albert/collections: API-facing collection classes that call endpoints.
+- src/albert/resources: Pydantic models representing API resources.
+- src/albert/core: Session, pagination, shared enums, and base classes.
+- src/albert/utils: Reusable helper utilities used by collections/resources.
+- docs/: mkdocs content (autogenerated from docstrings via mkdocstrings).
+- tests/: pytest suites, fixtures, and seed helpers.
+
+## API and Modeling Conventions
+
+- Collections inherit from BaseCollection and accept an AlbertSession.
+- Public collection methods should use @validate_call for runtime validation.
+- Resources use BaseAlbertModel/BaseResource with Pydantic Fields and aliases.
+- Keep API payloads in the wire format (camelCase) via Field(alias=...) and
+  model_dump(by_alias=True, mode="json", exclude_none=True).
+- Prefer narrow, explicit payload construction instead of dumping entire models.
+
+## Pagination
+
+Many list/search methods use AlbertPaginator (src/albert/core/pagination.py).
+Two modes exist:
+
+- Offset pagination (PaginationMode.OFFSET)
+  - Uses the offset query parameter.
+  - Defaults to limit=1000.
+  - Continues until Items is empty.
+
+- Key pagination (PaginationMode.KEY)
+  - Uses startKey and expects lastKey in the response.
+  - Page size defaults to backend behavior.
+
+Guidelines:
+
+- Expose a max_items parameter on public list/search methods where appropriate.
+  It is used to stop iteration early regardless of mode.
+- If a method returns an iterator, ensure the paginator is used consistently and
+  that the last_key can be inspected for resuming.
+- Use clear docstrings about offset/startKey behavior and max_items semantics.
+
+## Testing
+
+- Tests use pytest (see tests/).
+- Integration-style tests require environment variables:
+  - ALBERT_CLIENT_ID_SDK
+  - ALBERT_CLIENT_SECRET_SDK
+  - ALBERT_BASE_URL
+- The FakeAlbertSession in tests/utils supports unit-style tests without hitting
+  the network. Prefer it for pure behavior/unit tests.
+- Seed helpers live in tests/seeding.py and are reused across fixtures.
+
+## Documentation
+
+- Docs are built with mkdocs + mkdocstrings.
+- When adding a new resource/collection, add a docs page in docs/ and link it in
+  mkdocs.yml (alphabetical in nav).
+- Prefer docstrings for API reference content and keep them Numpy-style.
+
+## Release and Versioning
+
+- Version is defined in src/albert/**init**.py and read dynamically by Hatch.
+- Releases are created by tagging a version and drafting a GitHub release.
+
+## Do/Don’t Summary
+
+Do:
+
+- Add changelog entries for user-visible changes.
+- Keep docstrings Numpy-style for public APIs.
+- Use ruff for formatting/linting and respect line length 99.
+- Follow existing collection/resource patterns and naming.
+
+Don’t:
+
+- Add new public APIs without docstrings and tests.
+- Bypass Conventional Commits in commit messages.
+- Introduce new dependencies without strong justification.

{albert-1.13.0b2 → albert-1.14.1}/CHANGELOG.md

@@ -5,7 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [1.14.0] - 2025-01-29
+
+### Added
+
+- Added `ACLContainer` model for `{class, fgclist}` ACL payloads.
+- Added `WorksheetCollection.duplicate_sheet` functionality.
+- Added `WorksheetCollection.create_sheet_template` functionality.
+- Added a deprecation warning for `NotebookCopyACL`; formal deprecation planned for 2.0 (use `ACLContainer`).
 
 ## [1.2.0] - 2025-07-25
 

{albert-1.13.0b2 → albert-1.14.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: albert
-Version: 1.13.0b2
+Version: 1.14.1
 Summary: The official Python SDK for the Albert Invent platform.
 Project-URL: Homepage, https://www.albertinvent.com/
 Project-URL: Documentation, https://docs.developer.albertinvent.com/albert-python

albert-1.14.1/docs/assets/Albert_Wordmark_Mono_RGB_White.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 450.4 124.83">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #fff;
+      }
+    </style>
+  </defs>
+  <path class="cls-1" d="M155.73,0v114.36h-18.95V0h18.95Z"/>
+  <path class="cls-1" d="M172.72,114.36V0h18.79v45.75c5.88-8.17,16.01-13.4,27.12-13.4,22.06,0,39.05,18.13,39.05,41.98s-16.99,41.99-39.05,41.99c-11.11,0-21.24-4.74-27.12-12.91v10.95h-18.79ZM214.7,49.5c-13.56,0-24.01,10.95-24.01,24.83s10.45,24.83,24.01,24.83,24.01-10.95,24.01-24.83-10.45-24.83-24.01-24.83Z"/>
+  <path class="cls-1" d="M342.63,95.57c-6.7,12.58-19.28,20.75-36.11,20.75-24.34,0-41.66-17.32-41.66-41.99s17.48-41.98,40.68-41.98,39.86,18.14,39.86,41.98c0,3.11-.17,5.23-.17,5.72h-61.59c.82,11.6,11.11,20.26,23.03,20.26,10.46,0,15.85-5.06,20.42-12.09l15.52,7.35h0ZM326.61,66.33c-1.14-10.62-9.96-18.46-21.4-18.46s-20.26,9.31-21.4,18.46h42.8Z"/>
+  <path class="cls-1" d="M394.25,49.8c-13.88,0-22.38,8.32-22.38,24.82v39.73h-18.79V34.31h18.62v13.72c3.92-9.31,14.12-15.55,28.02-15.55v17.32h-5.47M407.08,6.84h20.33v25.64h22.98v17.33h-22.98v34.14c0,9.55,4.24,13.79,13.43,13.79,3.18,0,6.9-.89,9.55-2.65v18.21c-3.36,1.77-8.49,3.18-15.56,3.18-17.33,0-27.76-10.78-27.76-28.82V6.84h0Z"/>
+  <path class="cls-1" d="M119.79,66.31V0h-17.74L0,114.36h24L102.29,26.62v39.7h-18.67c-8.94,0-16.92,5.34-20.34,13.59-3.42,8.25-1.55,17.68,4.77,24l14.47,14.47c6.32,6.32,15.74,8.19,23.99,4.77,8.26-3.42,13.27-11.41,13.27-20.34v-19.49h9.63v-17h-9.63,0ZM102.29,102.8c0,2.13-1.13,3.82-3.1,4.64-.67.28-1.34.42-2,.42-1.27,0-2.47-.51-3.46-1.5l-14.47-14.47c-1.5-1.5-1.9-3.5-1.09-5.47.81-1.97,2.5-3.1,4.64-3.1h19.49v19.49h0Z"/>
+</svg>

albert-1.14.1/docs/assets/Albert_Wordmark_RGB_Colour.svg

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 450.4 124.83">
+  <defs>
+    <style>
+      .cls-1 {
+        fill: #7d19fe;
+      }
+    </style>
+  </defs>
+  <path class="cls-1" d="M155.73,0v114.36h-18.95V0h18.95Z"/>
+  <path class="cls-1" d="M172.72,114.36V0h18.79v45.75c5.88-8.17,16.01-13.4,27.12-13.4,22.06,0,39.05,18.13,39.05,41.98s-16.99,41.99-39.05,41.99c-11.11,0-21.24-4.74-27.12-12.91v10.95h-18.79ZM214.7,49.5c-13.56,0-24.01,10.95-24.01,24.83s10.45,24.83,24.01,24.83,24.01-10.95,24.01-24.83-10.45-24.83-24.01-24.83Z"/>
+  <path class="cls-1" d="M342.63,95.57c-6.7,12.58-19.28,20.75-36.11,20.75-24.34,0-41.66-17.32-41.66-41.99s17.48-41.98,40.68-41.98,39.86,18.14,39.86,41.98c0,3.11-.17,5.23-.17,5.72h-61.59c.82,11.6,11.11,20.26,23.03,20.26,10.46,0,15.85-5.06,20.42-12.09l15.52,7.35h0ZM326.61,66.33c-1.14-10.62-9.96-18.46-21.4-18.46s-20.26,9.31-21.4,18.46h42.8Z"/>
+  <path class="cls-1" d="M394.25,49.8c-13.88,0-22.38,8.32-22.38,24.82v39.73h-18.79V34.31h18.62v13.72c3.92-9.31,14.12-15.55,28.02-15.55v17.32h-5.47M407.08,6.84h20.33v25.64h22.98v17.33h-22.98v34.14c0,9.55,4.24,13.79,13.43,13.79,3.18,0,6.9-.89,9.55-2.65v18.21c-3.36,1.77-8.49,3.18-15.56,3.18-17.33,0-27.76-10.78-27.76-28.82V6.84h0Z"/>
+  <path class="cls-1" d="M119.79,66.31V0h-17.74L0,114.36h24L102.29,26.62v39.7h-18.67c-8.94,0-16.92,5.34-20.34,13.59-3.42,8.25-1.55,17.68,4.77,24l14.47,14.47c6.32,6.32,15.74,8.19,23.99,4.77,8.26-3.42,13.27-11.41,13.27-20.34v-19.49h9.63v-17h-9.63,0ZM102.29,102.8c0,2.13-1.13,3.82-3.1,4.64-.67.28-1.34.42-2,.42-1.27,0-2.47-.51-3.46-1.5l-14.47-14.47c-1.5-1.5-1.9-3.5-1.09-5.47.81-1.97,2.5-3.1,4.64-3.1h19.49v19.49h0Z"/>
+</svg>

albert-1.14.1/docs/assets/favicon_bw.svg

@@ -0,0 +1,4 @@
+<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
+<rect x="2" y="2" width="28" height="28" rx="14" fill="black"/>
+<path d="M22.2329 15.4998V7H19.9031L6.5 21.6587H9.65181L19.9358 10.4118V15.4998H17.4838C16.31 15.4998 15.2613 16.1836 14.8125 17.2417C14.3637 18.2997 14.6091 19.5071 15.4395 20.3175L17.3401 22.1722C18.1705 22.9817 19.4077 23.2221 20.4919 22.7841C21.577 22.3452 22.2348 21.3218 22.2348 20.1772V17.6796H23.5V15.5007H22.2348L22.2329 15.4998ZM19.9348 20.1763C19.9348 20.4495 19.7865 20.6662 19.528 20.7709C19.4403 20.8064 19.3517 20.8246 19.2649 20.8246C19.0988 20.8246 18.9402 20.7591 18.8105 20.6316L16.9099 18.7768C16.7121 18.5838 16.6599 18.3289 16.7672 18.0757C16.8745 17.8235 17.0956 17.6787 17.3765 17.6787H19.9358V20.1763H19.9348Z" fill="white"/>
+</svg>

{albert-1.13.0b2 → albert-1.14.1}/docs/index.md

@@ -1,8 +1,8 @@
 # Albert Python
 
 <div class="logo-wrapper">
-  <img src="assets/Wordmark_White.png" class="logo only-dark" alt="Albert Logo">
-  <img src="assets/Wordmark_Black.png" class="logo only-light" alt="Albert Logo">
+  <img src="assets/Albert_Wordmark_Mono_RGB_White.svg" class="logo only-dark" alt="Albert Logo">
+  <img src="assets/Albert_Wordmark_RGB_Colour.svg" class="logo only-light" alt="Albert Logo">
 </div>
 
 [![CI](https://img.shields.io/circleci/build/github/albert-labs/albert-python/main?label=CI)](https://app.circleci.com/pipelines/github/albert-labs/albert-python?branch=main)

albert-1.14.1/docs/resources/acls.md

@@ -0,0 +1 @@
+::: albert.resources.acls

{albert-1.13.0b2 → albert-1.14.1}/docs/styles/extra.css

@@ -1,6 +1,13 @@
 :root {
-  --md-primary-fg-color: #0149ff;
-  --md-accent-fg-color: #0149ff;
+  --md-primary-fg-color: #7D19FE;
+  --md-accent-fg-color: #7D19FE;
+}
+
+.md-typeset a:hover,
+.md-nav__link:hover,
+.md-nav--primary .md-nav__link:hover,
+.md-nav--secondary .md-nav__link:hover {
+  color: #0b62fe;
 }
 
 .logo-wrapper {

{albert-1.13.0b2 → albert-1.14.1}/mkdocs.yml

@@ -24,8 +24,8 @@ theme:
   name: "material"
   font:
     text: Aeonik Regular
-  logo: assets/Wordmark_White.png
-  favicon: assets/Vector_Favicon_Blue.svg
+  logo: assets/Albert_Wordmark_Mono_RGB_White.svg
+  favicon: assets/favicon_bw.svg
   features:
     - content.tabs.link # Tabs can contain links
     - content.code.annotate # Annotated code blocks (tooltips)
@@ -177,6 +177,7 @@ nav:
       - Resources:
           - Activities: resources/activities.md
           - Attachments: resources/attachments.md
+          - ACL: resources/acls.md
           - Batch Data: resources/batch_data.md
           - Breakthrough:
               - Breakthrough Datasets: resources/btdataset.md

{albert-1.13.0b2 → albert-1.14.1}/scripts/validate_version_bump.py

@@ -1,6 +1,7 @@
 import argparse
+import re
+import subprocess
 import sys
-from os import popen
 from pathlib import Path
 
 from packaging import version
@@ -19,8 +20,15 @@ def main(base_branch: str):
     local_path = Path(__file__).parents[1] / version_file
     local_version = extract_version(local_path.read_text())
 
-    with popen(f"git fetch origin && git show {base_branch}:{version_file}") as fh:
-        base_version = extract_version(fh.read())
+    if not re.fullmatch(r"[A-Za-z0-9._/-]+", base_branch) or base_branch.startswith("-"):
+        raise ValueError(f"Invalid base branch ref: {base_branch!r}")
+
+    subprocess.run(["git", "fetch", "origin"], check=True)
+    base_contents = subprocess.check_output(
+        ["git", "show", f"{base_branch}:{version_file}"],
+        text=True,
+    )
+    base_version = extract_version(base_contents)
 
     if is_version_bump(local_version, base_version):
         print(f"Version bump detected: {base_version} -> {local_version}")

{albert-1.13.0b2 → albert-1.14.1}/src/albert/__init__.py

@@ -4,4 +4,4 @@ from albert.core.auth.sso import AlbertSSOClient
 
 __all__ = ["Albert", "AlbertClientCredentials", "AlbertSSOClient"]
 
-__version__ = "1.13.0b2"
+__version__ = "1.14.1"

{albert-1.13.0b2 → albert-1.14.1}/src/albert/collections/attachments.py

@@ -152,20 +152,30 @@ class AttachmentCollection(BaseCollection):
             The name of the file, by default ""
         upload_key : str | None, optional
             Override the storage key used when signing and uploading the file.
-            Defaults to the provided ``file_name``.
+            Defaults to ``{parent_id}/{note_id}/{file_name}``.
 
         Returns
         -------
         Note
             The created note.
         """
-        upload_name = upload_key or file_name
-        if not upload_name:
+        if not (upload_key or file_name):
             raise ValueError("A file name or upload key must be provided for attachment upload.")
 
-        file_type = mimetypes.guess_type(file_name or upload_name)[0]
-        file_collection = self._get_file_collection()
         note_collection = self._get_note_collection()
+        note = Note(
+            parent_id=parent_id,
+            note=note_text,
+        )
+        registered_note = note_collection.create(note=note)
+        if upload_key:
+            attachment_name = file_name or Path(upload_key).name
+            upload_name = upload_key
+        else:
+            attachment_name = file_name
+            upload_name = f"{parent_id}/{registered_note.id}/{file_name}"
+        file_type = mimetypes.guess_type(attachment_name or upload_name)[0]
+        file_collection = self._get_file_collection()
 
         file_collection.sign_and_upload_file(
             data=file_data,
@@ -176,16 +186,12 @@ class AttachmentCollection(BaseCollection):
         file_info = file_collection.get_by_name(
             name=upload_name, namespace=FileNamespace.RESULT.value
         )
-        note = Note(
-            parent_id=parent_id,
-            note=note_text,
-        )
-        registered_note = note_collection.create(note=note)
         self.attach_file_to_note(
             note_id=registered_note.id,
-            file_name=file_name or Path(upload_name).name,
+            file_name=attachment_name,
             file_key=file_info.name,
         )
+
         return note_collection.get_by_id(id=registered_note.id)
 
     @validate_call

{albert-1.13.0b2 → albert-1.14.1}/src/albert/collections/projects.py

@@ -142,17 +142,17 @@ class ProjectCollection(BaseCollection):
         ----------
         text : str, optional
             Full-text search query.
-        status : list of str, optional
+        status : list[str], optional
             Filter by project statuses.
-        market_segment : list of str, optional
+        market_segment : list[str], optional
             Filter by market segment.
-        application : list of str, optional
+        application : list[str], optional
             Filter by application.
-        technology : list of str, optional
+        technology : list[str], optional
             Filter by technology tags.
-        created_by : list of str, optional
+        created_by : list[str], optional
             Filter by user names who created the project.
-        location : list of str, optional
+        location : list[str], optional
             Filter by location(s).
         from_created_at : str, optional
             Earliest creation date in 'YYYY-MM-DD' format.
@@ -162,15 +162,15 @@ class ProjectCollection(BaseCollection):
             Facet field to filter on.
         facet_text : str, optional
             Facet text to search for.
-        contains_field : list of str, optional
+        contains_field : list[str], optional
             Fields to search inside.
-        contains_text : list of str, optional
+        contains_text : list[str], optional
             Values to search for within the `contains_field`.
         linked_to : str, optional
             Entity ID the project is linked to.
         my_project : bool, optional
             If True, return only projects owned by current user.
-        my_role : list of str, optional
+        my_role : list[str], optional
             User roles to filter by.
         order_by : OrderBy, optional
             Sort order. Default is DESCENDING.