Skip to content

Commit 7cf1b25

Browse files
committed
Added Own Modules / Packages
1 parent a554a86 commit 7cf1b25

File tree

1 file changed

+67
-0
lines changed

1 file changed

+67
-0
lines changed

docs/user-guide/faq.md

+67
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,10 @@ The same applies when the error is shown in devtools/console where unfortunately
180180

181181
This area contains most common questions, hacks, or hints we provide to the community.
182182

183+
!!! Note
184+
185+
We have a lovely *PyScript* contributor, namely [Jeff Glass](https://github.com/jeffersglass), who is maintaining an awesome blog full of [PyScript Recipes](https://pyscript.recipes/) with even more use cases and solutions. If you cannot find what you are looking for in here, please do check over there as it's very likely there is something close to the answer you are looking for.
186+
183187
### PyScript latest
184188

185189
For various reasons previously discussed at length, we decided to remove our `latest` channel from our own CDN.
@@ -361,4 +365,67 @@ In this example we'll see MicroPython waving before Pyodide and finally an *ever
361365
</script>
362366
```
363367

368+
### Python Modules
369+
370+
There are a few ways to host or include other modules in *PyScript*:
371+
372+
* having the module already part of either *Pyodide* or *MicroPython* distribution
373+
* hosting on *GitHub* some file that need to be discovered and fetched at runtime as *package*
374+
* provide your own `module.py` as single file to include in the File System
375+
* create a folder with structured files and sub folders that can easily be *zipped* or *tar.gz* as unique entry, and let the File System do the rest
376+
377+
#### Hosting on GitHub
378+
379+
Beside modules already available behind the interpreter packages manager, it is possible to point directly at files in GitHub (or GitLab, or anywhere else the file can be downloaded without issues):
380+
381+
```python title="MicroPython mip example"
382+
# Install default version from micropython-lib
383+
mip.install("keyword")
384+
385+
# Install from raw URL
386+
mip.install("https://raw.githubusercontent.com/micropython/micropython-lib/master/python-stdlib/bisect/bisect.py")
387+
388+
# Install from GitHub shortcut
389+
mip.install("github:jeffersglass/some-project/foo.py")
390+
```
391+
392+
These URLs are recognized as *packages* entries in the *config* and as long as the URL allows *CORS* (fetching files from other domains) everything should be fine.
393+
394+
#### Provide your own file
395+
396+
Instead of using the *config* to define packages one can use the `files` field to bring modules in the runtime.
397+
398+
```html title="Module as File"
399+
<mpy-config>
400+
[files]
401+
"./modules/bisect.py" = "./bisect.py"
402+
</mpy-config>
403+
<script type="mpy">
404+
import bisect
405+
</script>
406+
```
407+
408+
#### Zip or Tar Gz Modules
409+
410+
With this approach it's possible to archive in a compressed way the module content with a simple to complex structure:
411+
412+
```
413+
my_module/__init__.py
414+
my_module/util.py
415+
my_module/sub/sub_util.py
416+
```
417+
418+
Once archived as `.zip` or as `.tar.gz` in a way that contains the *my_module* folder and its content, it's possible to host this remotely or simply have it reachable locally:
419+
420+
```html title="Module as File"
421+
<mpy-config>
422+
[files]
423+
"./my_module.zip" = "./*"
424+
</mpy-config>
425+
<script type="mpy">
426+
from my_module import util
427+
from my_module.sub import sub_util
428+
</script>
429+
```
364430

431+
Please **note** the `./*` convention, through a `.zip` or `.tar.gz` source, where the target folder with a star `*` will contain anything present in the source archive, in this example the whole *my_module* folder.

0 commit comments

Comments
 (0)