Package: brip
brip - The Brython Package Installerbripstands forBrython's pip.
It brings the Python packages ecosystem and the pip-like workflow to Brython-powered projects.You can usebripto install packages from thePyPIand other indexes, into your different Brython project.Problem StatementHistorically, mostbrython-orientedPython packages are
pre-compiled into - and distributed as - a javascript file.
This works well for those self-contained Python packages,
but when/if a Python package has its own dependencies,
there was no obvious way to declare and manage those dependencies.In general, there was no Pythonic way to install ageneric Pythonpackage
and their dependencies, directly from PyPI into your Brython project.bripis developed to bring the PyPI ecosystem and the familiar pip-like workflow
to Brython-powered projects.Quickstart: A complete sample projectThere is a complete sample project,Easter,
to demonstrate how to usebrip.InstallationJust runpip install brip.It is recommended that you installbripinto one central virtual environment,rather thaninstallingbripinside each of your brython project's environment.
(In fact, your Brython project technically does not need its own virtual environment.)Installation on Linux and macOS:python3 -m venv ~/venv_central
source ~/venv_central/bin/activate
pip install bripInstallation on Windows:py -m venv $HOME\venv_central
$HOME\venv_central\Scripts\activate.bat
pip install bripManual: Command-line usageThis manual assumes you use Linux or macOS.
Windows users please adjust the path separator in each sample.Install a package fromPyPIinto your Brython project's
web root directory (i.e. the directory containing yourindex.html):cd my_brython_project_one/website
brip install SomePackageNow a newsite-packages.brython.jsis generated in current directory,
containing SomePackageand its dependencies.
Your Brython project'sindex.htmlwould just need to add a line<script src="site-packages.brython.js"></script>,
from now on you can useimport some_packageinside your Brython project!Package installed bybripis obtained directly from PyPI.
You doNOTneed to install the package bypipfirst.List what packages are installed for current Brython project
(or more precisely speaking, list packages contained insite-packages.brython.js):cd my_brython_project_one/website
brip listNote:
Packages installed bybripare not visible topip list, and vice versa.
Because their installation target are completely different.Install several packages fromPyPIinto your Brython project's
web root directory (i.e. the directory containing yourindex.html):cd my_brython_project_two/website
brip install -r brequirements.txtThe file "brequirements.txt" hasa format identical topip's "requirements.txt",
and it can be named whatever name you want.
We recommend using a namedifferent thanpip's conventional "requirements.txt",
though, such as "brequirements.txt",
to remind you that its content are meant to be installed bybrip, not bypip.Uninstalling a package ... is not directly supported, but can be achieved by
organizing your full dependency list in a "brequirements.txt" file,
and then use this pattern:cd my_brython_project_two/website

# Use your editor to remove one package name
edit brequirements.txt

# Each install will OVERWRITE existing site-packages.brython.js
brip install -r brequirements.txtDifferences topipInpipyou can do incremental installation.
If you runpip install fooand thenpip install bar,
you would end up with bothfooandbarinstalled.But, due to some technical reason,bripalways do overwrite installation.
If you runbrip install fooand thenbrip install bar,
you would end up with onlybaravailable in your Brython project.Therefore, we recommend you always use a "brequirements.txt"
to organize your project's full dependency.
That way, any adjustment to such a file would be flushed to your Brython project
by nextbrip install -r brequirements.txt.bripalso only implements a small subset ofpip.
Please refer to the command-line helpbrip -horbrip install -hetc..Limitationsbripaims to bring the entire Python Package Index (PyPI) ecosystem to Brython.
However, in reality there are some limitations outside of the control ofbrip.Brython-powered applications are running inside a browser.
The browser is a capable virtual machine in its own right.
However, many Python packages are not expected to be run inside a browser.
For example, file system behaves differently in Brython: Writing is impossible,
and reading is limited to the folders accessible with an Ajax request.Brython itself only supports pure Python packages.
That excludes packages which are partially written in C, such asnumpy.
Consequently, only those packages written in pure Pythonand its entire dependency chainwritten in pure Python, would work in Brython.As of this writing, Brython 3.10.5 does not support convertingnamespace packagesinto a loadable javascript file.Sometimes, even pure Python package might not work in Brython, due to some subtledifferences between Brython and CPython.Unfortunately, there is currently no straightforward way to know
whether a Python package would work in Brython.
You probably have to rely on trial-and-error.
Just usebripto install a package, use it in Brython environment,
and see if the browser console logs any error.Feel free to report those packages intobrip's issue list.bripmight not be in position to solve it directly,
but the community might be able to help.Recipe for Brython-friendly package's maintainersWhile we mentioned in the Problem Statement thatbripwas mainly developed to
allow Brython app developers to pull generic Python packages from PyPI, for example:# Inside the brequirements.txt, it contains the following line
charts.css.py>=0.4,<1there is nothing wrong for a self-contained, Brython-friendly package to
be distributed as a javascript file, for example:<!-- Inside the index.html, it contains the following line --><scriptsrc='https://github.com/rayluo/charts.css.py/releases/download/0.4.0/charts.css.py-brython.js'></script>Here, the term "Brython-friendly" is defined as a generic, pure Python package
that can be released to PyPI, but it is also designed to be able to work in Brython.So, how do you - a Brython-friendly package's maintainer - generate that javascript file?Here is how I pack my packagecharts.css.pyinto acharts.css.py-brython.js:cd charts.css.py
brip install .
# Now a site-packages.brython.js is generated in current directory,
# containing the PyPI-ready project in current directory.
# I just need to rename it to charts.css.py-brython.js and distribute it.While doing so, you may see a warning message on your console:DEPRECATION: A future pip version will change local packages to be built in-place without first copying to a temporary directory. We recommend you use --use-feature=in-tree-build to test your packages with this new behavior before it becomes the default.
   pip 21.3 will remove support for this functionality. You can find discussion regarding this at https://github.com/pypa/pip/issues/7555.You can just ignore that message. It has no negative impact to your javascript outcome.That warning message is expected to be gone once pip 21.3 becomes available
and you upgrade to it (by runningpython -m pip install --upgrade pip).