Metadata-Version: 2.4
Name: mfiles-grpc
Version: 26.11.0
Summary: Client for the M-Files gRPC API: generated stubs, connection, login and errors
Author: M-Files
License-Expression: MIT
Project-URL: Documentation, https://developer.m-files.com/APIs/gRPC-API/
Project-URL: Source, https://github.com/M-Files/mfiles-grpc-python
Keywords: M-Files,gRPC,document management,ECM
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: grpcio>=1.85.1
Requires-Dist: protobuf<8,>=7.36.2
Provides-Extra: keyring
Requires-Dist: keyring>=25.0; extra == "keyring"
Dynamic: license-file

# M-Files gRPC API client for Python

The Python package `mfiles-grpc` for the M-Files gRPC API, with runnable examples: a quickstart
and one program per task recipe. The guides on
[developer.m-files.com](https://developer.m-files.com/APIs/gRPC-API/) embed their code.

The package has two parts:

* `mfiles`: the stubs generated from the M-Files protos, one module per service
  (`from mfiles import IRPCSearch_pb2, IRPCSearch_pb2_grpc, structs_pb2`).
* `mfiles_grpc`: what the protos cannot express. `MFilesClient` opens the channel (TLS or not,
  an optional custom root certificate, the message size limits of M-Files' own client), adds the
  M-Files call metadata and cookies to every call, logs in and out (with a password, a token or
  through the browser), decodes errors into `MFilesError` and keeps the vault's metadata
  structure version. `mfiles_grpc.values` builds object IDs, typed values, search conditions and
  ACLs; `mfiles_grpc.sso` and `mfiles_grpc.token_cache` sign in through the browser.

The package is a preview: its helpers can still change between releases.

## Install

From PyPI, the version for your server (see [Versions](#versions)):

```shell
pip install mfiles-grpc                  # add [keyring] to remember browser sign-ins
```

Or from this folder, which needs the protos (the `proto` folder of the API bundle, or `proto/`
here):

```shell
python -m venv .venv
.venv/bin/pip install -r requirements.txt        # Windows: .venv\Scripts\pip ...
.venv/bin/python generate.py [PROTO_DIR]
.venv/bin/pip install -e .
```

`generate.py` writes the stubs into `src/mfiles/`. Without `PROTO_DIR` it uses
`$MFILES_PROTO_DIR`, `proto/`, `../../proto` (the layout of the documentation download, where
`samples/` and `proto/` are siblings) or the bundle built in the M-Files repository.

Python 3.10 or newer.

## Configure

`MFilesClient.from_env()` and the examples read environment variables:

| Variable | Meaning |
|---|---|
| `MFILES_ADDRESS` | `host:port` of the gRPC endpoint, e.g. `myvault.cloudvault.m-files.com:443` or `myserver:7766` |
| `MFILES_TLS` | `true` (default) or `false` for a server without TLS |
| `MFILES_CA_CERT` | Optional: a PEM file of root certificates to trust, e.g. for a self-signed certificate |
| `MFILES_VAULT` | The vault GUID, with braces |
| `MFILES_USERNAME`, `MFILES_PASSWORD` | An M-Files user account |
| `MFILES_AUTH` | `browser` to sign in through the browser with the vault's OAuth plugin, such as M-Files Login Service; then `MFILES_VAULT` is optional |
| `MFILES_REMEMBER_SIGN_IN` | `true` to keep the refresh token of a browser sign-in in the operating system's credential store (needs `keyring`) |
| `MFILES_TOKEN`, `MFILES_AUTH_PLUGIN`, `MFILES_AUTH_SCOPE` | Or a token from the vault's identity provider, and optionally the authentication plugin and its configuration scope |

M-Files Cloud: port 443 with TLS. On-premises: the server's gRPC port, by default 7766; use
`MFILES_TLS=false` only if the server has no certificate configured.

## Examples

```shell
python examples/quickstart.py
python examples/recipes/search.py 1 30 10
```

| Program | What it shows | Arguments (all optional) |
|---|---|---|
| `quickstart.py` | Log in and list the 10 most recently modified documents | |
| `recipes/connect.py` | Server version, capabilities, log in, session info, keep-alive, log out | |
| `recipes/find_vault.py` | Find a vault's GUID by its name and open a session to it | vault name (the first vault); `MFILES_VAULT` is not needed |
| `recipes/login_service.py` | Sign in through M-Files Login Service in the browser | `--remember` |
| `recipes/vault_structure.py` | Object types, classes, property definitions; resolve an ID by alias | class alias, property alias |
| `recipes/search.py` | Documents of a class modified in the last N days, newest first | class ID (1), days (30), limit (10) |
| `recipes/read_object.py` | An object's latest version and its typed property values | object ID (437), object type (0) |
| `recipes/download_file.py` | Download a document's file | document ID (437), folder (`mfiles-grpc-samples` in the temporary folder) |
| `recipes/create_document.py` | Upload a file and create a document | `--keep` |
| `recipes/update_properties.py` | Change properties with an explicit version, and with check out / check in | `--keep` |
| `recipes/workflow_state.py` | Workflow states and allowed transitions; change the state | workflow ID (107), initial state (137), target state (141), `--keep` |
| `recipes/paging.py` | Go through a large result set page by page | page size (100) |
| `recipes/errors.py` | Handle "not found" and "access denied" | |

The programs are in `examples/`. The defaults suit the M-Files Sample Vault. Recipes that write
create documents whose titles start with `[docs-test]` and delete them at the end unless you pass
`--keep`.

A failed call raises `mfiles_grpc.MFilesError`, which carries the gRPC status (`status`), the
message (`message`), the M-Files error code of the top-level error (`hresult`, `hresult_hex`,
`hresult_signed`), the codes of the whole error stack (`codes`) and `has(code)` to test for a
code anywhere in it.

## Tests

```shell
python -m unittest discover -s tests      # unit tests; no server needed
python run_tests.py                        # the unit tests, then every example against a vault
```

`run_tests.py` uses the package from `src/`, reads `~/.mfiles-grpc-docs/test-config.json`
(section `local`), sets the variables above, runs the quickstart and every recipe as the
configured user and fails if any of them fails (except `recipes/login_service.py`, which needs a
person to sign in in the browser). If the section also has an `admin` account, it then destroys
the deleted `[docs-test]` objects that the recipes left behind. See the docstring of
`run_tests.py` for the file format.

## Versions

There is one package version per M-Files Server release: `26.11.0` is for 26.11, `26.11.1` a
revision of it. A version works with its server release and later ones; with an older server,
methods that the server does not have fail with `UNIMPLEMENTED`.

## License

MIT; see [LICENSE](LICENSE).
