Teams API

TeamCollection is accessed via ManagementProject.teams. It provides the full collection contract for teams in a project.

proj = mgmt.project("proj_grating_7f3a")
teams = proj.teams  # TeamCollection

The Team object

Team is not a frozen dataclass — it carries a bound TeamMembershipCollection alongside the optional member_count field, which @dataclass field-ordering rules do not allow. The public surface is:

TeamCollection.get(team_id, *, include=())

Fetch a single team by ID. Raises if the team does not exist.

Signature

def get(self, team_id: str, *, include: Sequence[TeamInclude] = ()) -> Team: ...

Parameters

Returns — Team: the requested team.

Side effects — Makes one HTTP read request.

Raises — NotFoundError when no team with team_id exists in the project. AuthenticationError when the API key is invalid or missing.

Example

team = proj.teams.get("team_abc123", include=("counts",))
print(team.name, team.member_count)

TeamCollection.get_or_none(team_id, *, include=())

Fetch a single team by ID. Returns None instead of raising when the team does not exist.

Signature

def get_or_none(self, team_id: str, *, include: Sequence[TeamInclude] = ()) -> Team | None: ...

Parameters

Returns — Team if found, None if not found.

Side effects — Makes one HTTP read request.

Raises — AuthenticationError when the API key is invalid or missing. Does NOT raise NotFoundError.

Example

team = proj.teams.get_or_none("team_maybe")
if team:
    print(team.name)

TeamCollection.list(...)

Return one page of teams matching the given filters.

Signature

def list(
    self,
    *,
    name: str | None = None,
    category: str | None = None,
    include: Sequence[TeamInclude] = (),
    limit: int = 100,
    cursor: str | None = None,
    order_by: TeamOrderBy = "name",
    order: Literal["asc", "desc"] = "asc",
) -> Page[Team]: ...

Parameters

Returns — Page[Team]: items, next_cursor, total. See Collection contract for Page field details.

Side effects — Makes one HTTP read request.

Raises — AuthenticationError when the API key is invalid or missing.

Example

page = proj.teams.list(category="simulation", include=("counts",), order_by="created_at", order="desc")
for team in page.items:
    print(team.name, team.member_count)

TeamCollection.iter(...)

Iterate over all teams matching the given filters across all pages.

Signature

def iter(
    self,
    *,
    name: str | None = None,
    category: str | None = None,
    include: Sequence[TeamInclude] = (),
    order_by: TeamOrderBy = "name",
    order: Literal["asc", "desc"] = "asc",
) -> Iterator[Team]: ...

Parameters

Returns — Iterator[Team]: a lazy iterator that fetches pages on demand.

Side effects — Makes one HTTP read request per page fetched.

Raises — AuthenticationError on any page fetch.

Example

for team in proj.teams.iter(include=("counts",)):
    print(f"{team.name}: {team.member_count} members")

TeamCollection.count(*, category=None)

Return the count of teams in the project, optionally filtered by category.

Signature

def count(self, *, category: str | None = None) -> int: ...

Parameters

Returns — int: the total number of matching teams.

Side effects — Makes one HTTP read request.

Raises — AuthenticationError when the API key is invalid or missing.

Example

total = proj.teams.count()
sim_teams = proj.teams.count(category="simulation")
print(f"{sim_teams}/{total} teams are simulation teams")

TeamCollection.one(...)

Return exactly one team matching the given filters. Raises if zero or more than one team matches.

Signature

def one(
    self,
    *,
    name: str | None = None,
    category: str | None = None,
    include: Sequence[TeamInclude] = (),
) -> Team: ...

Parameters

Returns — Team: the single matching team.

Side effects — Makes one HTTP read request (fetches up to 2 items to detect ambiguity).

Raises — NotFoundError when no teams match. MultipleResultsError when more than one team matches. AuthenticationError when the API key is invalid or missing.

Example

team = proj.teams.one(name="Photonics Lab")

TeamCollection.first(...)

Return the first team matching the given filters, or None if no teams match.

Signature

def first(
    self,
    *,
    name: str | None = None,
    category: str | None = None,
    include: Sequence[TeamInclude] = (),
) -> Team | None: ...

Parameters

Returns — Team if at least one team matches, None otherwise. Ordered by order_by default ("name" ascending).

Side effects — Makes one HTTP read request (fetches exactly 1 item).

Raises — AuthenticationError when the API key is invalid or missing.

Example

team = proj.teams.first(category="simulation")
if team:
    print(team.name)

Accessing memberships on a team

Every Team instance carries a bound TeamMembershipCollection at .memberships. Use it to query the members of that specific team:

team = proj.teams.get("team_abc123", include=("counts",))
for membership in team.memberships.iter():
    print(membership.user_ref.id, membership.role)

See Memberships API for full documentation.