| Name | brip JSON |
| Version |
0.3.0
JSON |
| download |
| home_page | https://github.com/rayluo/brip |
| Summary | brip stands for Brython's pip. It brings the Python Package Index (PyPI) ecosystem and the pip-like workflow to Brython-powered project. |
| upload_time | 2023-10-22 04:33:05 |
| maintainer | |
| docs_url | None |
| author | Ray Luo |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
pip
brython
package
install
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# brip - The Brython Package Installer
`brip` stands for [Brython](https://brython.info/)'s pip.
It brings the Python packages ecosystem and the pip-like workflow to Brython-powered projects.
You can use `brip` to install packages from the [PyPI](https://pypi.org) and other indexes, into your different Brython project.
## Problem Statement
* Historically, most **brython-oriented** Python 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 a **generic Python** package
and their dependencies, directly from PyPI into your Brython project.
`brip` is developed to bring the PyPI ecosystem and the familiar pip-like workflow
to Brython-powered projects.
## Quickstart: A complete sample project
There is a complete sample project, [Easter](https://github.com/rayluo/easter),
to demonstrate how to use `brip`.
## Installation
Just run `pip install brip`.
It is recommended that you install `brip` into one central virtual environment,
*rather than* installing `brip` inside 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 brip
```
Installation on Windows:
```
py -m venv $HOME\venv_central
$HOME\venv_central\Scripts\activate.bat
pip install brip
```
## Manual: Command-line usage
This manual assumes you use Linux or macOS.
Windows users please adjust the path separator in each sample.
* Install a package from [PyPI](https://pypi.org) into your Brython project's
web root directory (i.e. the directory containing your `index.html`):
```
cd my_brython_project_one/website
brip install SomePackage
```
Now a new `site-packages.brython.js` is generated in current directory,
containing SomePackage *and its dependencies*.
Your Brython project's `index.html` would just need to add a line
`<script src="site-packages.brython.js"></script>`,
from now on you can use `import some_package` inside your Brython project!
Package installed by `brip` is obtained directly from PyPI.
You do *NOT* need to install the package by `pip` first.
* List what packages are installed for current Brython project
(or more precisely speaking, list packages contained in `site-packages.brython.js`):
```
cd my_brython_project_one/website
brip list
```
Note:
Packages installed by `brip` are not visible to `pip list`, and vice versa.
Because their installation target are completely different.
* Install several packages from [PyPI](https://pypi.org) into your Brython project's
web root directory (i.e. the directory containing your `index.html`):
```
cd my_brython_project_two/website
brip install -r brequirements.txt
```
The file "**b**requirements.txt" has
[a format identical to `pip`'s "requirements.txt"](https://pip.pypa.io/en/stable/cli/pip_install/#requirements-file-format),
and it can be named whatever name you want.
We recommend using a name *different than* pip's conventional "requirements.txt",
though, such as "**b**requirements.txt",
to remind you that its content are meant to be installed by `brip`, not by `pip`.
* Uninstalling a package ... is not directly supported, but can be achieved by
organizing your full dependency list in a "**b**requirements.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.txt
```
## Differences to `pip`
In `pip` you can do incremental installation.
If you run `pip install foo` and then `pip install bar`,
you would end up with both `foo` and `bar` installed.
But, due to some technical reason, `brip` always do overwrite installation.
If you run `brip install foo` and then `brip install bar`,
you would end up with only `bar` available in your Brython project.
Therefore, we recommend you always use a "**b**requirements.txt"
to organize your project's full dependency.
That way, any adjustment to such a file would be flushed to your Brython project
by next `brip install -r brequirements.txt`.
`brip` also only implements a small subset of `pip`.
Please refer to the command-line help `brip -h` or `brip install -h` etc..
## Limitations
`brip` aims to bring the entire Python Package Index (PyPI) ecosystem to Brython.
However, in reality there are some limitations outside of the control of `brip`.
* 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 as `numpy`.
Consequently, only those packages written in pure Python
*and its entire dependency chain* written in pure Python, would work in Brython.
* As of this writing, Brython 3.10.5 does not support converting
[namespace packages](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/)
into a loadable javascript file.
* Sometimes, even pure Python package might not work in Brython, due to some subtle
[differences between Brython and CPython](https://brython.info/static_doc/en/stdlib.html).
* 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 use `brip` to install a package, use it in Brython environment,
and see if the browser console logs any error.
Feel free to report those packages into
[brip's issue list](https://github.com/rayluo/brip/issues).
`brip` might not be in position to solve it directly,
but the community might be able to help.
## Recipe for Brython-friendly package's maintainers
While we mentioned in the Problem Statement that `brip` was 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,<1
```
there is nothing wrong for a self-contained, Brython-friendly package to
be distributed as a javascript file, for example:
```html
<!-- Inside the index.html, it contains the following line -->
<script src='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 package
[`charts.css.py`](https://github.com/rayluo/charts.css.py/releases/tag/0.4.0)
into a `charts.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 running `python -m pip install --upgrade pip`).
Raw data
{
"_id": null,
"home_page": "https://github.com/rayluo/brip",
"name": "brip",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "pip,brython,package,install",
"author": "Ray Luo",
"author_email": "rayluo.mba@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/d6/23/2077319c9b93b1418ce6c671c6bf779a702e5c7145e4679fde937d59d0c8/brip-0.3.0.tar.gz",
"platform": null,
"description": "# brip - The Brython Package Installer\n\n`brip` stands for [Brython](https://brython.info/)'s pip.\nIt brings the Python packages ecosystem and the pip-like workflow to Brython-powered projects.\n\nYou can use `brip` to install packages from the [PyPI](https://pypi.org) and other indexes, into your different Brython project.\n\n\n## Problem Statement\n\n* Historically, most **brython-oriented** Python packages are\n pre-compiled into - and distributed as - a javascript file.\n This works well for those self-contained Python packages,\n but when/if a Python package has its own dependencies,\n there was no obvious way to declare and manage those dependencies.\n* In general, there was no Pythonic way to install a **generic Python** package\n and their dependencies, directly from PyPI into your Brython project.\n\n`brip` is developed to bring the PyPI ecosystem and the familiar pip-like workflow\nto Brython-powered projects.\n\n\n## Quickstart: A complete sample project\n\nThere is a complete sample project, [Easter](https://github.com/rayluo/easter),\nto demonstrate how to use `brip`.\n\n\n## Installation\n\nJust run `pip install brip`.\n\nIt is recommended that you install `brip` into one central virtual environment,\n*rather than* installing `brip` inside each of your brython project's environment.\n(In fact, your Brython project technically does not need its own virtual environment.)\n\nInstallation on Linux and macOS:\n\n```\npython3 -m venv ~/venv_central\nsource ~/venv_central/bin/activate\npip install brip\n```\n\nInstallation on Windows:\n\n```\npy -m venv $HOME\\venv_central\n$HOME\\venv_central\\Scripts\\activate.bat\npip install brip\n```\n\n\n## Manual: Command-line usage\n\nThis manual assumes you use Linux or macOS.\nWindows users please adjust the path separator in each sample.\n\n* Install a package from [PyPI](https://pypi.org) into your Brython project's\n web root directory (i.e. the directory containing your `index.html`):\n\n ```\n cd my_brython_project_one/website\n brip install SomePackage\n ```\n\n Now a new `site-packages.brython.js` is generated in current directory,\n containing SomePackage *and its dependencies*.\n Your Brython project's `index.html` would just need to add a line\n `<script src=\"site-packages.brython.js\"></script>`,\n from now on you can use `import some_package` inside your Brython project!\n\n Package installed by `brip` is obtained directly from PyPI.\n You do *NOT* need to install the package by `pip` first.\n\n\n* List what packages are installed for current Brython project\n (or more precisely speaking, list packages contained in `site-packages.brython.js`):\n\n ```\n cd my_brython_project_one/website\n brip list\n ```\n\n Note:\n Packages installed by `brip` are not visible to `pip list`, and vice versa.\n Because their installation target are completely different.\n\n\n* Install several packages from [PyPI](https://pypi.org) into your Brython project's\n web root directory (i.e. the directory containing your `index.html`):\n\n ```\n cd my_brython_project_two/website\n brip install -r brequirements.txt\n ```\n\n The file \"**b**requirements.txt\" has\n [a format identical to `pip`'s \"requirements.txt\"](https://pip.pypa.io/en/stable/cli/pip_install/#requirements-file-format),\n and it can be named whatever name you want.\n We recommend using a name *different than* pip's conventional \"requirements.txt\",\n though, such as \"**b**requirements.txt\",\n to remind you that its content are meant to be installed by `brip`, not by `pip`.\n\n\n* Uninstalling a package ... is not directly supported, but can be achieved by\n organizing your full dependency list in a \"**b**requirements.txt\" file,\n and then use this pattern:\n\n ```\n cd my_brython_project_two/website\n\n # Use your editor to remove one package name\n edit brequirements.txt\n\n # Each install will OVERWRITE existing site-packages.brython.js\n brip install -r brequirements.txt\n ```\n\n\n## Differences to `pip`\n\nIn `pip` you can do incremental installation.\nIf you run `pip install foo` and then `pip install bar`,\nyou would end up with both `foo` and `bar` installed.\n\nBut, due to some technical reason, `brip` always do overwrite installation.\nIf you run `brip install foo` and then `brip install bar`,\nyou would end up with only `bar` available in your Brython project.\n\nTherefore, we recommend you always use a \"**b**requirements.txt\"\nto organize your project's full dependency.\nThat way, any adjustment to such a file would be flushed to your Brython project\nby next `brip install -r brequirements.txt`.\n\n`brip` also only implements a small subset of `pip`.\nPlease refer to the command-line help `brip -h` or `brip install -h` etc..\n\n\n## Limitations\n\n`brip` aims to bring the entire Python Package Index (PyPI) ecosystem to Brython.\nHowever, in reality there are some limitations outside of the control of `brip`.\n\n* Brython-powered applications are running inside a browser.\n The browser is a capable virtual machine in its own right.\n However, many Python packages are not expected to be run inside a browser.\n For example, file system behaves differently in Brython: Writing is impossible,\n and reading is limited to the folders accessible with an Ajax request.\n\n* Brython itself only supports pure Python packages.\n That excludes packages which are partially written in C, such as `numpy`.\n Consequently, only those packages written in pure Python\n *and its entire dependency chain* written in pure Python, would work in Brython.\n\n* As of this writing, Brython 3.10.5 does not support converting\n [namespace packages](https://packaging.python.org/en/latest/guides/packaging-namespace-packages/)\n into a loadable javascript file.\n\n* Sometimes, even pure Python package might not work in Brython, due to some subtle\n [differences between Brython and CPython](https://brython.info/static_doc/en/stdlib.html).\n\n* Unfortunately, there is currently no straightforward way to know\n whether a Python package would work in Brython.\n You probably have to rely on trial-and-error.\n Just use `brip` to install a package, use it in Brython environment,\n and see if the browser console logs any error.\n\nFeel free to report those packages into\n[brip's issue list](https://github.com/rayluo/brip/issues).\n`brip` might not be in position to solve it directly,\nbut the community might be able to help.\n\n\n## Recipe for Brython-friendly package's maintainers\n\nWhile we mentioned in the Problem Statement that `brip` was mainly developed to\nallow Brython app developers to pull generic Python packages from PyPI, for example:\n\n```\n# Inside the brequirements.txt, it contains the following line\ncharts.css.py>=0.4,<1\n```\n\nthere is nothing wrong for a self-contained, Brython-friendly package to\nbe distributed as a javascript file, for example:\n\n```html\n<!-- Inside the index.html, it contains the following line -->\n<script src='https://github.com/rayluo/charts.css.py/releases/download/0.4.0/charts.css.py-brython.js'></script>\n```\n\nHere, the term \"Brython-friendly\" is defined as a generic, pure Python package\nthat can be released to PyPI, but it is also designed to be able to work in Brython.\n\nSo, how do you - a Brython-friendly package's maintainer - generate that javascript file?\n\nHere is how I pack my package\n[`charts.css.py`](https://github.com/rayluo/charts.css.py/releases/tag/0.4.0)\ninto a `charts.css.py-brython.js`:\n\n```\ncd charts.css.py\nbrip install .\n# Now a site-packages.brython.js is generated in current directory,\n# containing the PyPI-ready project in current directory.\n# I just need to rename it to charts.css.py-brython.js and distribute it.\n```\n\nWhile doing so, you may see a warning message on your console:\n\n```\n 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.\n pip 21.3 will remove support for this functionality. You can find discussion regarding this at https://github.com/pypa/pip/issues/7555.\n```\n\nYou can just ignore that message. It has no negative impact to your javascript outcome.\n\nThat warning message is expected to be gone once pip 21.3 becomes available\nand you upgrade to it (by running `python -m pip install --upgrade pip`).\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "brip stands for Brython's pip. It brings the Python Package Index (PyPI) ecosystem and the pip-like workflow to Brython-powered project.",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/rayluo/brip/releases",
"Homepage": "https://github.com/rayluo/brip"
},
"split_keywords": [
"pip",
"brython",
"package",
"install"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "334cb867553f7f225443e2c0f20d249d6a6860bc97464911e59ea0586cdf58c1",
"md5": "9c40fcd66c2ab06d549089df5258cea3",
"sha256": "cac3435588704b9db7f84440dab5be4ff1fed3f61deedf9d2f4957bcad190c4a"
},
"downloads": -1,
"filename": "brip-0.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "9c40fcd66c2ab06d549089df5258cea3",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": ">=3.7",
"size": 8173,
"upload_time": "2023-10-22T04:33:03",
"upload_time_iso_8601": "2023-10-22T04:33:03.460415Z",
"url": "https://files.pythonhosted.org/packages/33/4c/b867553f7f225443e2c0f20d249d6a6860bc97464911e59ea0586cdf58c1/brip-0.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d6232077319c9b93b1418ce6c671c6bf779a702e5c7145e4679fde937d59d0c8",
"md5": "fab245a867d3e77df1104f3feb995895",
"sha256": "61eb69f49b6dd14c0b66c2a6b1a6570ea75c83eb9bfcb7d568b8d2742d3992bc"
},
"downloads": -1,
"filename": "brip-0.3.0.tar.gz",
"has_sig": false,
"md5_digest": "fab245a867d3e77df1104f3feb995895",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 8727,
"upload_time": "2023-10-22T04:33:05",
"upload_time_iso_8601": "2023-10-22T04:33:05.030910Z",
"url": "https://files.pythonhosted.org/packages/d6/23/2077319c9b93b1418ce6c671c6bf779a702e5c7145e4679fde937d59d0c8/brip-0.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-22 04:33:05",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rayluo",
"github_project": "brip",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "brip"
}
