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.MFilesClientopens 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 intoMFilesErrorand keeps the vault's metadata structure version.mfiles_grpc.valuesbuilds object IDs, typed values, search conditions and ACLs;mfiles_grpc.ssoandmfiles_grpc.token_cachesign in through the browser.
The package is a preview: its helpers can still change between releases.
From PyPI, the version for your server (see Versions):
pip install mfiles-grpc # add [keyring] to remember browser sign-insOr 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.
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.
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.
python -m unittest discover -s tests # unit tests; no server needed
python run_tests.py # the unit tests, then every example against a vaultrun_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.
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.
MIT; see LICENSE.