Skip to content

About

Python client for the M-Files gRPC API: connect, log in (password or SSO), read and write objects, and manage the vault's metadata structure.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

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 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):

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):

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

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

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.

About

Python client for the M-Files gRPC API: connect, log in (password or SSO), read and write objects, and manage the vault's metadata structure.

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages