2022-07-05 15:25:53 +03:00
<!DOCTYPE HTML>
< html lang = "en" class = "sidebar-visible no-js light" >
< head >
<!-- Book generated using mdBook -->
< meta charset = "UTF-8" >
< title > Dependency management - Synapse< / title >
<!-- Custom HTML head -->
< meta content = "text/html; charset=utf-8" http-equiv = "Content-Type" >
< meta name = "description" content = "" >
< meta name = "viewport" content = "width=device-width, initial-scale=1" >
< meta name = "theme-color" content = "#ffffff" / >
< link rel = "icon" href = "../favicon.svg" >
< link rel = "shortcut icon" href = "../favicon.png" >
< link rel = "stylesheet" href = "../css/variables.css" >
< link rel = "stylesheet" href = "../css/general.css" >
< link rel = "stylesheet" href = "../css/chrome.css" >
< link rel = "stylesheet" href = "../css/print.css" media = "print" >
<!-- Fonts -->
< link rel = "stylesheet" href = "../FontAwesome/css/font-awesome.css" >
< link rel = "stylesheet" href = "../fonts/fonts.css" >
<!-- Highlight.js Stylesheets -->
< link rel = "stylesheet" href = "../highlight.css" >
< link rel = "stylesheet" href = "../tomorrow-night.css" >
< link rel = "stylesheet" href = "../ayu-highlight.css" >
<!-- Custom theme stylesheets -->
< link rel = "stylesheet" href = "../docs/website_files/table-of-contents.css" >
< link rel = "stylesheet" href = "../docs/website_files/remove-nav-buttons.css" >
< link rel = "stylesheet" href = "../docs/website_files/indent-section-headers.css" >
2023-12-12 20:29:11 +03:00
< link rel = "stylesheet" href = "../docs/website_files/version-picker.css" >
2022-07-05 15:25:53 +03:00
< / head >
< body >
<!-- Provide site root to javascript -->
< script type = "text/javascript" >
var path_to_root = "../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "light";
< / script >
<!-- Work around some values being stored in localStorage wrapped in quotes -->
< script type = "text/javascript" >
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') & & theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') & & sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
< / script >
<!-- Set the theme before any content is loaded, prevents flash -->
< script type = "text/javascript" >
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
var html = document.querySelector('html');
html.classList.remove('no-js')
html.classList.remove('light')
html.classList.add(theme);
html.classList.add('js');
< / script >
<!-- Hide / unhide sidebar before it is displayed -->
< script type = "text/javascript" >
var html = document.querySelector('html');
var sidebar = 'hidden';
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
}
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
< / script >
< nav id = "sidebar" class = "sidebar" aria-label = "Table of contents" >
< div class = "sidebar-scrollbox" >
2023-11-17 16:44:41 +03:00
< ol class = "chapter" > < li class = "chapter-item expanded affix " > < li class = "part-title" > Introduction< / li > < li class = "chapter-item expanded " > < a href = "../welcome_and_overview.html" > Welcome and Overview< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Setup< / li > < li class = "chapter-item expanded " > < a href = "../setup/installation.html" > Installation< / a > < / li > < li class = "chapter-item expanded " > < a href = "../postgres.html" > Using Postgres< / a > < / li > < li class = "chapter-item expanded " > < a href = "../reverse_proxy.html" > Configuring a Reverse Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "../setup/forward_proxy.html" > Configuring a Forward/Outbound Proxy< / a > < / li > < li class = "chapter-item expanded " > < a href = "../turn-howto.html" > Configuring a Turn Server< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../setup/turn/coturn.html" > coturn TURN server< / a > < / li > < li class = "chapter-item expanded " > < a href = "../setup/turn/eturnal.html" > eturnal TURN server< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../delegate.html" > Delegation< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Upgrading< / li > < li class = "chapter-item expanded " > < a href = "../upgrade.html" > Upgrading between Synapse Versions< / a > < / li > < li class = "chapter-item expanded affix " > < li class = "part-title" > Usage< / li > < li class = "chapter-item expanded " > < a href = "../federate.html" > Federation< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/index.html" > Configuration< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../usage/configuration/config_documentation.html" > Configuration Manual< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/homeserver_sample_config.html" > Homeserver Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/logging_sample_config.html" > Logging Sample Config File< / a > < / li > < li class = "chapter-item expanded " > < a href = "../structured_logging.html" > Structured Logging< / a > < / li > < li class = "chapter-item expanded " > < a href = "../templates.html" > Templates< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/index.html" > User Authentication< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/single_sign_on/index.html" > Single-Sign On< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../openid.html" > OpenID Connect< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/single_sign_on/saml.html" > SAML< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/single_sign_on/cas.html" > CAS< / a > < / li > < li class = "chapter-item expanded " > < a href = "../sso_mapping_providers.html" > SSO Mapping Providers< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../password_auth_providers.html" > Password Auth Providers< / a > < / li > < li class = "chapter-item expanded " > < a href = "../jwt.html" > JSON Web Tokens< / a > < / li > < li class = "chapter-item expanded " > < a href = "../usage/configuration/user_authentication/refresh_tokens.html" > Refresh Tokens< / a > < / li > < / ol > < / li > < li class = "chapter-item expanded " > < a href = "../CAPTCHA_SETUP.html" > Registration Captcha< / a > < / li > < li class = "chapter-item expanded " > < a href = "../application_services.html" > Application Services< / a > < / li > < li class = "chapter-item expanded " > < a href = "../server_notices.html" > Server Notices< / a > < / li > < li class = "chapter-item expanded " > < a href = "../consent_tracking.html" > Consent Tracking< / a > < / li > < li class = "chapter-item expanded " > < a href = "../user_directory.html" > User Directory< / a > < / li > < li class = "chapter-item expanded " > < a href = "../message_retention_policies.html" > Message Retention Policies< / a > < / li > < li class = "chapter-item expanded " > < a href = "../modules/index.html" > Pluggable Modules< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded " > < a href = "../modules/writing_a_module.html" > Writing a module< / a > < / li > < li > < ol class = "section" > < li class = "chapter-item expanded "
2022-07-05 15:25:53 +03:00
< / div >
< div id = "sidebar-resize-handle" class = "sidebar-resize-handle" > < / div >
< / nav >
< div id = "page-wrapper" class = "page-wrapper" >
< div class = "page" >
< div id = "menu-bar-hover-placeholder" > < / div >
< div id = "menu-bar" class = "menu-bar sticky bordered" >
< div class = "left-buttons" >
< button id = "sidebar-toggle" class = "icon-button" type = "button" title = "Toggle Table of Contents" aria-label = "Toggle Table of Contents" aria-controls = "sidebar" >
< i class = "fa fa-bars" > < / i >
< / button >
< button id = "theme-toggle" class = "icon-button" type = "button" title = "Change theme" aria-label = "Change theme" aria-haspopup = "true" aria-expanded = "false" aria-controls = "theme-list" >
< i class = "fa fa-paint-brush" > < / i >
< / button >
< ul id = "theme-list" class = "theme-popup" aria-label = "Themes" role = "menu" >
< li role = "none" > < button role = "menuitem" class = "theme" id = "light" > Light (default)< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "rust" > Rust< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "coal" > Coal< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "navy" > Navy< / button > < / li >
< li role = "none" > < button role = "menuitem" class = "theme" id = "ayu" > Ayu< / button > < / li >
< / ul >
< button id = "search-toggle" class = "icon-button" type = "button" title = "Search. (Shortkey: s)" aria-label = "Toggle Searchbar" aria-expanded = "false" aria-keyshortcuts = "S" aria-controls = "searchbar" >
< i class = "fa fa-search" > < / i >
< / button >
2023-12-12 20:29:11 +03:00
< div class = "version-picker" >
< div class = "dropdown" >
< div class = "select" >
< span > < / span >
< i class = "fa fa-chevron-down" > < / i >
< / div >
< input type = "hidden" name = "version" >
< ul class = "dropdown-menu" >
<!-- Versions will be added dynamically in version - picker.js -->
< / ul >
< / div >
2024-01-16 19:12:52 +03:00
< / div >
2022-07-05 15:25:53 +03:00
< / div >
< h1 class = "menu-title" > Synapse< / h1 >
< div class = "right-buttons" >
< a href = "../print.html" title = "Print this book" aria-label = "Print this book" >
< i id = "print-button" class = "fa fa-print" > < / i >
< / a >
2024-01-16 19:12:52 +03:00
< a href = "https://github.com/element-hq/synapse" title = "Git repository" aria-label = "Git repository" >
2022-07-05 15:25:53 +03:00
< i id = "git-repository-button" class = "fa fa-github" > < / i >
< / a >
2024-01-16 19:12:52 +03:00
< a href = "https://github.com/element-hq/synapse/edit/develop/docs/development/dependencies.md" title = "Suggest an edit" aria-label = "Suggest an edit" >
2022-07-05 15:25:53 +03:00
< i id = "git-edit-button" class = "fa fa-edit" > < / i >
< / a >
< / div >
< / div >
< div id = "search-wrapper" class = "hidden" >
< form id = "searchbar-outer" class = "searchbar-outer" >
< input type = "search" id = "searchbar" name = "searchbar" placeholder = "Search this book ..." aria-controls = "searchresults-outer" aria-describedby = "searchresults-header" >
< / form >
< div id = "searchresults-outer" class = "searchresults-outer hidden" >
< div id = "searchresults-header" class = "searchresults-header" > < / div >
< ul id = "searchresults" >
< / ul >
< / div >
< / div >
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
< script type = "text/javascript" >
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
< / script >
< div id = "content" class = "content" >
< main >
<!-- Page table of contents -->
< div class = "sidetoc" >
< nav class = "pagetoc" > < / nav >
< / div >
< h1 id = "managing-dependencies-with-poetry" > < a class = "header" href = "#managing-dependencies-with-poetry" > Managing dependencies with Poetry< / a > < / h1 >
< p > This is a quick cheat sheet for developers on how to use < a href = "https://python-poetry.org/" > < code > poetry< / code > < / a > .< / p >
2023-01-31 21:36:56 +03:00
< h1 id = "installing" > < a class = "header" href = "#installing" > Installing< / a > < / h1 >
< p > See the < a href = "contributing_guide.html#4-install-the-dependencies" > contributing guide< / a > .< / p >
< p > Developers should use Poetry 1.3.2 or higher. If you encounter problems related
to poetry, please < a href = "#check-the-version-of-poetry-with-poetry---version" > double-check your poetry version< / a > .< / p >
2022-07-05 15:25:53 +03:00
< h1 id = "background" > < a class = "header" href = "#background" > Background< / a > < / h1 >
< p > Synapse uses a variety of third-party Python packages to function as a homeserver.
Some of these are direct dependencies, listed in < code > pyproject.toml< / code > under the
< code > [tool.poetry.dependencies]< / code > section. The rest are transitive dependencies (the
things that our direct dependencies themselves depend on, and so on recursively.)< / p >
< p > We maintain a locked list of all our dependencies (transitive included) so that
we can track exactly which version of each dependency appears in a given release.
See < a href = "https://github.com/matrix-org/synapse/issues/11537#issue-1074469665" > here< / a >
for discussion of why we wanted this for Synapse. We chose to use
< a href = "https://python-poetry.org/" > < code > poetry< / code > < / a > to manage this locked list; see
< a href = "https://github.com/matrix-org/synapse/issues/11537#issuecomment-1015975819" > this comment< / a >
for the reasoning.< / p >
< p > The locked dependencies get included in our " self-contained" releases: namely,
our docker images and our debian packages. We also use the locked dependencies
in development and our continuous integration.< / p >
< p > Separately, our " broad" dependencies—the version ranges specified in
< code > pyproject.toml< / code > —are included as metadata in our " sdists" and " wheels" < a href = "https://pypi.org/project/matrix-synapse" > uploaded
to PyPI< / a > . Installing from PyPI or from
the Synapse source tree directly will < em > not< / em > use the locked dependencies; instead,
they'll pull in the latest version of each package available at install time.< / p >
< h2 id = "example-dependency" > < a class = "header" href = "#example-dependency" > Example dependency< / a > < / h2 >
< p > An example may help. We have a broad dependency on
< a href = "https://pypi.org/project/phonenumbers/" > < code > phonenumbers< / code > < / a > , as declared in
this snippet from pyproject.toml < a href = "https://github.com/matrix-org/synapse/blob/release-v1.57/pyproject.toml#L133" > as of Synapse 1.57< / a > :< / p >
< pre > < code class = "language-toml" > [tool.poetry.dependencies]
# ...
phonenumbers = " > =8.2.0"
< / code > < / pre >
< p > In our lockfile this is
< a href = "https://github.com/matrix-org/synapse/blob/dfc7646504cef3e4ff396c36089e1c6f1b1634de/poetry.lock#L679-L685" > pinned< / a >
to version 8.12.44, even though
< a href = "https://pypi.org/project/phonenumbers/#history" > newer versions are available< / a > .< / p >
< pre > < code class = "language-toml" > [[package]]
name = " phonenumbers"
version = " 8.12.44"
description = " Python version of Google's common library for parsing, formatting, storing and validating international phone numbers."
category = " main"
optional = false
python-versions = " *"
< / code > < / pre >
< p > The lockfile also includes a
< a href = "https://github.com/matrix-org/synapse/blob/release-v1.57/poetry.lock#L2178-L2181" > cryptographic checksum< / a >
of the sdists and wheels provided for this version of < code > phonenumbers< / code > .< / p >
< pre > < code class = "language-toml" > [metadata.files]
# ...
phonenumbers = [
{file = " phonenumbers-8.12.44-py2.py3-none-any.whl" , hash = " sha256:cc1299cf37b309ecab6214297663ab86cb3d64ae37fd5b88e904fe7983a874a6" },
{file = " phonenumbers-8.12.44.tar.gz" , hash = " sha256:26cfd0257d1704fe2f88caff2caabb70d16a877b1e65b6aae51f9fbbe10aa8ce" },
]
< / code > < / pre >
< p > We can see this pinned version inside the docker image for that release:< / p >
2024-01-16 19:12:52 +03:00
< pre > < code > $ docker pull vectorim/synapse:v1.97.0
2022-07-05 15:25:53 +03:00
...
2024-01-16 19:12:52 +03:00
$ docker run --entrypoint pip vectorim/synapse:v1.97.0 show phonenumbers
2022-07-05 15:25:53 +03:00
Name: phonenumbers
Version: 8.12.44
Summary: Python version of Google's common library for parsing, formatting, storing and validating international phone numbers.
Home-page: https://github.com/daviddrysdale/python-phonenumbers
Author: David Drysdale
Author-email: dmd@lurklurk.org
License: Apache License 2.0
Location: /usr/local/lib/python3.9/site-packages
Requires:
Required-by: matrix-synapse
< / code > < / pre >
< p > Whereas the wheel metadata just contains the broad dependencies:< / p >
< pre > < code > $ cd /tmp
$ wget https://files.pythonhosted.org/packages/ca/5e/d722d572cc5b3092402b783d6b7185901b444427633bd8a6b00ea0dd41b7/matrix_synapse-1.57.0rc1-py3-none-any.whl
...
$ unzip -c matrix_synapse-1.57.0rc1-py3-none-any.whl matrix_synapse-1.57.0rc1.dist-info/METADATA | grep phonenumbers
Requires-Dist: phonenumbers (> =8.2.0)
< / code > < / pre >
< h1 id = "tooling-recommendation-direnv" > < a class = "header" href = "#tooling-recommendation-direnv" > Tooling recommendation: direnv< / a > < / h1 >
< p > < a href = "https://direnv.net/" > < code > direnv< / code > < / a > is a tool for activating environments in your
shell inside a given directory. Its support for poetry is unofficial (a
community wiki recipe only), but works solidly in our experience. We thoroughly
recommend it for daily use. To use it:< / p >
< ol >
< li > < a href = "https://direnv.net/docs/installation.html" > Install < code > direnv< / code > < / a > - it's likely
packaged for your system already.< / li >
< li > Teach direnv about poetry. The < a href = "https://github.com/direnv/direnv/wiki/Python#poetry" > shell config here< / a >
needs to be added to < code > ~/.config/direnv/direnvrc< / code > (or more generally < code > $XDG_CONFIG_HOME/direnv/direnvrc< / code > ).< / li >
< li > Mark the synapse checkout as a poetry project: < code > echo layout poetry > .envrc< / code > .< / li >
< li > Convince yourself that you trust this < code > .envrc< / code > configuration and project.
Then formally confirm this to < code > direnv< / code > by running < code > direnv allow< / code > .< / li >
< / ol >
< p > Then whenever you navigate to the synapse checkout, you should be able to run
e.g. < code > mypy< / code > instead of < code > poetry run mypy< / code > ; < code > python< / code > instead of
< code > poetry run python< / code > ; and your shell commands will automatically run in the
context of poetry's venv, without having to run < code > poetry shell< / code > beforehand.< / p >
< h1 id = "how-do-i" > < a class = "header" href = "#how-do-i" > How do I...< / a > < / h1 >
< h2 id = "reset-my-venv-to-the-locked-environment" > < a class = "header" href = "#reset-my-venv-to-the-locked-environment" > ...reset my venv to the locked environment?< / a > < / h2 >
2023-01-31 21:36:56 +03:00
< pre > < code class = "language-shell" > poetry install --all-extras --sync
2022-07-05 15:25:53 +03:00
< / code > < / pre >
2022-09-27 15:50:14 +03:00
< h2 id = "delete-everything-and-start-over-from-scratch" > < a class = "header" href = "#delete-everything-and-start-over-from-scratch" > ...delete everything and start over from scratch?< / a > < / h2 >
< pre > < code class = "language-shell" > # Stop the current virtualenv if active
$ deactivate
# Remove all of the files from the current environment.
# Don't worry, even though it says " all" , this will only
# remove the Poetry virtualenvs for the current project.
$ poetry env remove --all
# Reactivate Poetry shell to create the virtualenv again
$ poetry shell
# Install everything again
$ poetry install --extras all
< / code > < / pre >
2022-07-05 15:25:53 +03:00
< h2 id = "run-a-command-in-the-poetry-virtualenv" > < a class = "header" href = "#run-a-command-in-the-poetry-virtualenv" > ...run a command in the < code > poetry< / code > virtualenv?< / a > < / h2 >
< p > Use < code > poetry run cmd args< / code > when you need the python virtualenv context.
To avoid typing < code > poetry run< / code > all the time, you can run < code > poetry shell< / code >
to start a new shell in the poetry virtualenv context. Within < code > poetry shell< / code > ,
< code > python< / code > , < code > pip< / code > , < code > mypy< / code > , < code > trial< / code > , etc. are all run inside the project virtualenv
and isolated from the rest o the system.< / p >
< p > Roughly speaking, the translation from a traditional virtualenv is:< / p >
< ul >
< li > < code > env/bin/activate< / code > -> < code > poetry shell< / code > , and< / li >
< li > < code > deactivate< / code > -> close the terminal (Ctrl-D, < code > exit< / code > , etc.)< / li >
< / ul >
< p > See also the direnv recommendation above, which makes < code > poetry run< / code > and
< code > poetry shell< / code > unnecessary.< / p >
< h2 id = "inspect-the-poetry-virtualenv" > < a class = "header" href = "#inspect-the-poetry-virtualenv" > ...inspect the < code > poetry< / code > virtualenv?< / a > < / h2 >
< p > Some suggestions:< / p >
< pre > < code class = "language-shell" > # Current env only
poetry env info
# All envs: this allows you to have e.g. a poetry managed venv for Python 3.7,
# and another for Python 3.10.
poetry env list --full-path
poetry run pip list
< / code > < / pre >
< p > Note that < code > poetry show< / code > describes the abstract < em > lock file< / em > rather than your
on-disk environment. With that said, < code > poetry show --tree< / code > can sometimes be
useful.< / p >
< h2 id = "add-a-new-dependency" > < a class = "header" href = "#add-a-new-dependency" > ...add a new dependency?< / a > < / h2 >
< p > Either:< / p >
< ul >
< li > manually update < code > pyproject.toml< / code > ; then < code > poetry lock --no-update< / code > ; or else< / li >
< li > < code > poetry add packagename< / code > . See < code > poetry add --help< / code > ; note the < code > --dev< / code > ,
2023-01-31 21:36:56 +03:00
< code > --extras< / code > and < code > --optional< / code > flags in particular.< / li >
2022-07-05 15:25:53 +03:00
< / ul >
< p > Include the updated < code > pyproject.toml< / code > and < code > poetry.lock< / code > files in your commit.< / p >
< h2 id = "remove-a-dependency" > < a class = "header" href = "#remove-a-dependency" > ...remove a dependency?< / a > < / h2 >
< p > This is not done often and is untested, but< / p >
< pre > < code class = "language-shell" > poetry remove packagename
< / code > < / pre >
< p > ought to do the trick. Alternatively, manually update < code > pyproject.toml< / code > and
2023-01-31 21:36:56 +03:00
< code > poetry lock --no-update< / code > . Include the updated < code > pyproject.toml< / code > and < code > poetry.lock< / code >
2022-07-05 15:25:53 +03:00
files in your commit.< / p >
< h2 id = "update-the-version-range-for-an-existing-dependency" > < a class = "header" href = "#update-the-version-range-for-an-existing-dependency" > ...update the version range for an existing dependency?< / a > < / h2 >
< p > Best done by manually editing < code > pyproject.toml< / code > , then < code > poetry lock --no-update< / code > .
Include the updated < code > pyproject.toml< / code > and < code > poetry.lock< / code > in your commit.< / p >
< h2 id = "update-a-dependency-in-the-locked-environment" > < a class = "header" href = "#update-a-dependency-in-the-locked-environment" > ...update a dependency in the locked environment?< / a > < / h2 >
< p > Use< / p >
< pre > < code class = "language-shell" > poetry update packagename
< / code > < / pre >
< p > to use the latest version of < code > packagename< / code > in the locked environment, without
affecting the broad dependencies listed in the wheel.< / p >
< p > There doesn't seem to be a way to do this whilst locking a < em > specific< / em > version of
< code > packagename< / code > . We can workaround this (crudely) as follows:< / p >
< pre > < code class = "language-shell" > poetry add packagename==1.2.3
# This should update pyproject.lock.
# Now undo the changes to pyproject.toml. For example
# git restore pyproject.toml
# Get poetry to recompute the content-hash of pyproject.toml without changing
# the locked package versions.
poetry lock --no-update
< / code > < / pre >
< p > Either way, include the updated < code > poetry.lock< / code > file in your commit.< / p >
< h2 id = "export-a-requirementstxt-file" > < a class = "header" href = "#export-a-requirementstxt-file" > ...export a < code > requirements.txt< / code > file?< / a > < / h2 >
< pre > < code class = "language-shell" > poetry export --extras all
< / code > < / pre >
< p > Be wary of bugs in < code > poetry export< / code > and < code > pip install -r requirements.txt< / code > .< / p >
< h2 id = "build-a-test-wheel" > < a class = "header" href = "#build-a-test-wheel" > ...build a test wheel?< / a > < / h2 >
< p > I usually use< / p >
< pre > < code class = "language-shell" > poetry run pip install build & & poetry run python -m build
< / code > < / pre >
< p > because < a href = "https://github.com/pypa/build" > < code > build< / code > < / a > is a standardish tool which
doesn't require poetry. (It's what we use in CI too). However, you could try
< code > poetry build< / code > too.< / p >
2023-02-14 18:28:53 +03:00
< h2 id = "handle-a-dependabot-pull-request" > < a class = "header" href = "#handle-a-dependabot-pull-request" > ...handle a Dependabot pull request?< / a > < / h2 >
2023-06-06 12:50:03 +03:00
< p > Synapse uses Dependabot to keep the < code > poetry.lock< / code > and < code > Cargo.lock< / code > file
up-to-date with the latest releases of our dependencies. The changelog check is
omitted for Dependabot PRs; the release script will include them in the
changelog.< / p >
< p > When reviewing a dependabot PR, ensure that:< / p >
2023-02-14 18:28:53 +03:00
< ul >
< li > the lockfile changes look reasonable;< / li >
< li > the upstream changelog file (linked in the description) doesn't include any
breaking changes;< / li >
2023-06-06 12:50:03 +03:00
< li > continuous integration passes.< / li >
2023-02-14 18:28:53 +03:00
< / ul >
< p > In particular, any updates to the type hints (usually packages which start with < code > types-< / code > )
should be safe to merge if linting passes.< / p >
2022-08-02 13:56:24 +03:00
< h1 id = "troubleshooting" > < a class = "header" href = "#troubleshooting" > Troubleshooting< / a > < / h1 >
< h2 id = "check-the-version-of-poetry-with-poetry---version" > < a class = "header" href = "#check-the-version-of-poetry-with-poetry---version" > Check the version of poetry with < code > poetry --version< / code > .< / a > < / h2 >
2023-01-31 21:36:56 +03:00
< p > The minimum version of poetry supported by Synapse is 1.3.2.< / p >
2022-08-02 13:56:24 +03:00
< p > It can also be useful to check the version of < code > poetry-core< / code > in use. If you've
installed < code > poetry< / code > with < code > pipx< / code > , try < code > pipx runpip poetry list | grep poetry-core< / code > .< / p >
< h2 id = "clear-caches-poetry-cache-clear---all-pypi" > < a class = "header" href = "#clear-caches-poetry-cache-clear---all-pypi" > Clear caches: < code > poetry cache clear --all pypi< / code > .< / a > < / h2 >
< p > Poetry caches a bunch of information about packages that isn't readily available
from PyPI. (This is what makes poetry seem slow when doing the first
< code > poetry install< / code > .) Try < code > poetry cache list< / code > and < code > poetry cache clear --all < name of cache> < / code > to see if that fixes things.< / p >
2022-09-27 15:50:14 +03:00
< h2 id = "remove-outdated-egg-info" > < a class = "header" href = "#remove-outdated-egg-info" > Remove outdated egg-info< / a > < / h2 >
< p > Delete the < code > matrix_synapse.egg-info/< / code > directory from the root of your Synapse
install.< / p >
< p > This stores some cached information about dependencies and often conflicts with
letting Poetry do the right thing.< / p >
2022-08-02 13:56:24 +03:00
< h2 id = "try---verbose-or---dry-run-arguments" > < a class = "header" href = "#try---verbose-or---dry-run-arguments" > Try < code > --verbose< / code > or < code > --dry-run< / code > arguments.< / a > < / h2 >
< p > Sometimes useful to see what poetry's internal logic is.< / p >
2022-07-05 15:25:53 +03:00
< / main >
< nav class = "nav-wrapper" aria-label = "Page navigation" >
<!-- Mobile navigation buttons -->
< a rel = "prev" href = "../development/experimental_features.html" class = "mobile-nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../development/synapse_architecture/cancellation.html" class = "mobile-nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< div style = "clear: both" > < / div >
< / nav >
< / div >
< / div >
< nav class = "nav-wide-wrapper" aria-label = "Page navigation" >
< a rel = "prev" href = "../development/experimental_features.html" class = "nav-chapters previous" title = "Previous chapter" aria-label = "Previous chapter" aria-keyshortcuts = "Left" >
< i class = "fa fa-angle-left" > < / i >
< / a >
< a rel = "next" href = "../development/synapse_architecture/cancellation.html" class = "nav-chapters next" title = "Next chapter" aria-label = "Next chapter" aria-keyshortcuts = "Right" >
< i class = "fa fa-angle-right" > < / i >
< / a >
< / nav >
< / div >
< script type = "text/javascript" >
window.playground_copyable = true;
< / script >
< script src = "../elasticlunr.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../mark.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../searcher.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../clipboard.min.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../highlight.js" type = "text/javascript" charset = "utf-8" > < / script >
< script src = "../book.js" type = "text/javascript" charset = "utf-8" > < / script >
<!-- Custom JS scripts -->
< script type = "text/javascript" src = "../docs/website_files/table-of-contents.js" > < / script >
2023-12-12 20:29:11 +03:00
< script type = "text/javascript" src = "../docs/website_files/version-picker.js" > < / script >
< script type = "text/javascript" src = "../docs/website_files/version.js" > < / script >
2022-07-05 15:25:53 +03:00
< / body >
2023-12-12 20:29:11 +03:00
< / html >
