Metadata-Version: 2.4
Name: xchem-ta-auth-client
Version: 1.2.0
Summary: The ISPyB Target Access Authenticator Client
Author-email: Alan Christie <achristie@informaticsmatters.com>
Maintainer-email: Alan Christie <achristie@informaticsmatters.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/xchem/fragalysis-target-access-authenticator-python-client.git
Keywords: api
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.32.4
Dynamic: license-file

# fragalysis-target-access-authenticator-python-client

![PyPI - Version](https://img.shields.io/pypi/v/xchem-ta-auth-client)

![release](https://github.com/xchem/fragalysis-target-access-authenticator-python-client/actions/workflows/release.yaml/badge.svg)


A simple Python 3 client to simplify access to the authenticator,
providing the following functions: -

```python
def get_auth_target_access(username: str) -> set[str]:
    [...]
def get_auth_users(target_access_string: str) -> TasAuthUsersGetResponse:
    [...]
def get_auth_version() -> TasAuthVersionGetResponse:
    [...]
def get_auth_ping() -> TasAuthPingGetResponse:
    [...]
```

`get_auth_users()` (which needs authenticator **1.5.0** or later) returns a
response rather than a bare set because, unlike `get_auth_target_access()`, it
has to distinguish _"the TAS has no members"_ from _"we could not find out"_: -

```python
response = ta_auth_connector.get_auth_users("lb32627-66")
if response.error:
    # We do not know who the members are - 'users' is empty but meaningless
    ...
else:
    # 'users' is the membership, and may legitimately be empty
    ...
```

From **1.2.0** the response also has `members`, the same users (sorted by login)
as `TasAuthMember` objects carrying each user's `given_name` and `family_name`.
These need authenticator **1.6.0** or later - with an older authenticator the
members are the users with names of `None`.

The module requires two items, extracted from the environment: -

-   `TA_AUTH_SERVICE` - The service hostname. In cluster this might be
    `http://auth.ta-authenticator.svc` (an internal connection that is expected to
    comply with http:// protocol)
-   `TA_AUTH_QUERY_KEY` - A 'secret' key the service expects in request headers.

## Usage
After installing from PyPI, access the `ta_auth_connector` functions directly
via the connector module: -

    import ta_auth_connector

    ping_response: TasAuthPingGetResponse = ta_auth_connector.get_auth_ping()

## Target access strings
A _Target Access String_ (**TAS**) is the concatenation of a two-character **code**
(lower case), **proposal number**, and **visit number** formatted
as `<code><proposal>-<visit>`: -

-   lb12345-1
-   lb32627-66

## Rules
Access to non-public Fragalysis Targets is limited to users who are members
of the associated TAS. If a target belongs to `lb32627-66` (and `lb32627-66` is not
a publicly visible target) you will not be permitted access to the material
unless, according to ISPyB, you are a member of proposal `32627` and visit `66`.

Also, although everyone can _view_ publicly visible targets you are not permitted
to alter or add material to the target unless you are a member of the corresponding
proposal and visit. Everyone can _see_ public targets, but only members of the TAS
can edit.

## The authenticator service
See: -

-   https://github.com/xchem/fragalysis-ispyb-target-access-authenticator
-   https://github.com/xchem/fragalysis-mock-target-access-authenticator

---
