diff --git a/README.md b/README.md index a763a9d..1f394b5 100644 --- a/README.md +++ b/README.md @@ -5,18 +5,18 @@ _Ready to use AppImages of Python are available as GitHub [releases][RELEASES]._ ## Quickstart -We provide relocatable Python runtimes as [AppImages][APPIMAGE] for Linux -systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker images, -and they are available as GitHub [releases][RELEASES]. Our Python AppImages are -updated weekly, on every Sunday. +We provide relocatable Python runtimes in the form of [AppImages][APPIMAGE] for +Linux systems. These runtimes are extracted from [Manylinux][MANYLINUX] Docker +images and are available as GitHub [releases][RELEASES]. Our Python AppImages +are updated weekly, on every Sunday. -Instructions for _installing_ and running _Python AppImages_ are provided on +Instructions for _installing_ and running _Python AppImages_ can be found on [Read the Docs][READTHEDOCS]. -In addition, the online documentation describes the [`python-appimage`][PYPI] -utility, for application developers. This utility can facilitate the building of -Python apps, given an existing Python AppImage and a recipe folder. -[Examples][APPLICATIONS] of recipes are available from GitHub. +The online documentation also describes the [`python-appimage`][PYPI] utility +for application developers. This utility can facilitate the development of +Python applications, provided you have an existing Python AppImage and a recipe +folder. [Examples][APPLICATIONS] of recipes are available on GitHub. ## Projects using [`python-appimage`][GITHUB] diff --git a/docs/include/references.md b/docs/include/references.md index 14719ff..c0b1268 100644 --- a/docs/include/references.md +++ b/docs/include/references.md @@ -12,7 +12,9 @@ [GITHUB]: {{ config.repo_url }} [LINUXDEPLOY]: https://github.com/linuxdeploy/linuxdeploy/ [MANYLINUX]: https://github.com/pypa/manylinux/ +[NUMPY]: https://numpy.org/ [PATCHELF]: https://github.com/NixOS/patchelf/ +[PEP_425]: https://peps.python.org/pep-0425/ [PYPI]: https://pypi.org/project/python-appimage/ [RELEASES]: {{ config.repo_url }}releases/ [SHEBANG]: https://en.wikipedia.org/wiki/Shebang_(Unix)/ diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index e005129..c2a0107 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -10,7 +10,7 @@ docs_dir: src nav: - Python AppImages: index.md - - Developers corner: apps.md + - Developers' corner: apps.md theme: name: readthedocs diff --git a/docs/src/apps.md b/docs/src/apps.md index 922d520..d1f26f3 100644 --- a/docs/src/apps.md +++ b/docs/src/apps.md @@ -10,157 +10,169 @@ {% include "references.md" %} -# Developers corner +# Developers' corner -Python [AppImages][APPIMAGE] are built with the `python-appimage` utility, -available from [PyPI][PYPI]. This utility can also help packaging Python based -applications as AppImages, using an existing Python AppImage and a recipe +Python [AppImages][APPIMAGE] are created using the `python-appimage` utility, +which is available on [PyPI][PYPI]. This utility can also be used to package +Python-based applications as AppImages using an existing AppImage and a recipe folder. !!! Caution The `python-appimage` utility can only package applications that can be - directly installed with `pip`. For more advanced usage, one needs to extract - the Python AppImage and to edit it, e.g. as explained in the [Advanced - installation](index.md#advanced-installation) section. Additional details - on this use case are provided [below](#advanced-packaging). + installed directly with `pip`. For more advanced usage, it is necessary to + extract and edit the Python AppImage, as explained in the [Advanced + installation](index.md#advanced-installation) section. Further details on + this use case can be found [below](#advanced-packaging). ## Building a Python AppImage -The primary scope of `python-appimage` is to relocate an existing Python -installation inside an AppDir, and to build the corresponding AppImage. For -example, the following +The primary purpose of `python-appimage` is to relocate an existing Python +installation to an AppDir and build the corresponding AppImage. For example, the +command ```bash python-appimage build local -p $(which python2) ``` -should build an AppImage of your local Python 2 installation, provided that it +should create an AppImage of your local Python installation, provided that it exists. !!! Tip - Help on available arguments and options to `python-appimage` can be obtained - with the `-h` flag. For example, `python-appimage build local -h` provides - help on local builds. + Help on the available arguments and options for `python-appimage` can be + obtained by using the `-h` flag. For example, running + `python-appimage build local -h` provides help on local builds. {{ begin(".capsule") }} ### Auxiliary tools The `python-appimage` utility relies on auxiliary tools that are downloaded and -installed at runtime, on need. Those are [appimagetool][APPIMAGETOOL] for -building AppImages, and [patchelf][PATCHELF] in order to edit ELFs runtime paths -(`RPATH`). Auxiliary tools are installed to the the user space. One can get -their location with the `which` command word. For example, +installed on demand during application execution. These are +[appimagetool][APPIMAGETOOL], which is used to build AppImages, and +[patchelf][PATCHELF], which is used to edit runtime paths (`RPATH`) in ELF +files. These auxiliary tools are installed in the application cache. Their +location can be found using the `which` command. For example, the command ```bash python-appimage which appimagetool ``` -returns the location of `appimagetool`, if it has been installed. If not, the -`install` command word can be used in order to trigger its installation. +returns the location of [appimagetool][APPIMAGETOOL] if it has been installed. +If not, the `install` command can be used to trigger its installation. {{ end(".capsule") }} ## Manylinux Python AppImages -AppImages of your local `python` are unlikely to be portable, except if you run -an ancient Linux distribution. Indeed, a core component preventing portability -across Linuses is the use of different versions of the `glibc` system library. -Hopefully, `glibc` is highly backward compatible. Therefore, a simple -work-around is to compile binaries using the oldest Linux distro you can afford -to. This is the strategy used for creating portable AppImages, as well as for -distributing Python site packages as ready-to-use binary [wheels][WHEELS]. +AppImages of your local `python` are unlikely to be portable, unless you are +running an outdated Linux distribution. A core component that prevents +portability across Linux distributions is the use of different versions of the +`glibc` system library. Fortunately, `glibc` is highly backward compatible. +Therefore, a simple workaround is to compile binaries using the oldest Linux +distribution you can. This strategy is used to create portable AppImages and to +distribute Python site packages as ready-to-use binary [wheels][WHEELS]. The Python Packaging Authority (PyPA) has defined standard platform tags for -building Python site packages, labelled [manylinux][MANYLINUX]. These build -platforms are available as Docker images with various versions of Python already -installed. The `python-appimage` utility can be used to package those installs -as AppImages. For example, the following command +building Python site packages labelled [Manylinux][MANYLINUX]. These build +platforms are available as Docker images, with different versions of Python +already installed. The `python-appimage` utility can be used to package these +installations as AppImages. For example, the following command ```bash -python-appimage build manylinux 2014_x86_64 cp310-cp310 +python-appimage build manylinux 2014_x86_64 cp313-cp313 ``` -should build an AppImage of Python 3.10 using the CPython (_cp310-cp310_) -install found in the `manylinux2014_x86_64` Docker image. +should build an AppImage of Python __3.13__ using the CPython (__cp313-cp313__) +installation found in the `manylinux2014_x86_64` Docker image. !!! Note - Docker needs to be already installed on your system in order to build - Manylinux Python images. However, the command above can be run on the host. - That is, you need **not** to explictly shell inside the manylinux Docker - image. + From version `1.4.0` of `python-appimage` onwards, Docker is **no longer** + required to build the Manylinux Python images. Cross-building is also + supported, for example producing an `aarch64` Python image from an `x86_64` + host. + +!!! Warning + Creating multiple Manylinux Python images can significantly increase the + size of the application cache. This can be managed using the + `python-appimage cache` command. !!! Tip - A compilation of ready-to-use Manylinux Python AppImages is available from - the [releases][RELEASES] area of the `python-appimage` [GitHub + A compilation of ready-to-use Manylinux Python AppImages is available in the + [releases][RELEASES] section of the `python-appimage` [GitHub repository][GITHUB]. These AppImages are updated weekly, on every Sunday. +!!! Tip + Instead of an AppImage, the `python-appimage build manylinux` command can + produce either an `AppDir` or a bare tarball (i.e. without the AppImage + layer) of a Manylinux Python installation. See the `-b` and `-n` command + line options for more information. ## Simple packaging -The `python-appimage` utility can also be used in order to build simple -applications, that can be `pip` installed. The syntax is +The `python-appimage` utility can also be used to package simple AppImage +applications, whose dependencies can be installed using `pip`. The syntax is ```bash -python-appimage build app -p 3.10 /path/to/recipe/folder +python-appimage build app -p 3.13 /path/to/recipe/folder ``` -in order to build a Python 3.10 based application from a recipe folder. -Examples of recipes can be found on GitHub in the [applications][APPLICATIONS] -folder. The recipe folder contains: +to build a Python 3.13-based application from a recipe folder. Examples of +recipes can be found in the [applications][APPLICATIONS] folder on GitHub. The +recipe folder contains - the AppImage metadata (`application.xml` and `application.desktop`), - an application icon (e.g. `application.png`), -- a Python requirements file (`requirements.txt`) +- a Python requirements file (`requirements.txt`), - an entry point script (`entrypoint.sh`). -Additional information on metadata can be found in the AppImage documentation. -That is, for [desktop][APPIMAGE_DESKTOP] and [AppStream XML][APPIMAGE_XML] -files. The `requirements.txt` file allows to specify additional site packages -to be bundled in the AppImage, using `pip`. +Further information on metadata can be found in the AppImage documentation +(e.g., regarding [desktop][APPIMAGE_DESKTOP] and [AppStream XML][APPIMAGE_XML] +files). The `requirements.txt` file enables additional site packages to be +specified for bundling in the AppImage using `pip`. !!! Caution - For the application to be portable, site packages bundled in the AppImage, - as well as their dependencies, must must be available as binary wheels, or - be pure Python packages. + In order for the application to be portable, the site packages bundled in + the AppImage and their dependencies must be available as binary wheels or + pure Python packages. - If a **C extension** is bundled from **source**, then it will likely **not - be portable**, as further discussed in the [Advanced + If a **C extension** is bundled from **source**, it will likely **not be + portable**; this is discussed further in the [Advanced packaging](#advanced-packaging) section. !!! Tip - Some site packages are available only for specific Manylinux tags. This can - be cross-checked by browsing the `Download files` section on the package's - PyPI page. + Some site packages are only available for specific Manylinux tags. You can + check this by browsing the `Download files` section on the package's PyPI + page. !!! Tip - Since version 1.2, `python-appimage` allows to specify local requirements as - well, using the `local+` tag (see - [PR49](https://github.com/niess/python-appimage/pull/49)). Note however that - this performs a direct copy of the local package, which has several - limitations. + Since version 1.2, `python-appimage` allows local requirements to be + specified using the `local+` tag (see + [PR49](https://github.com/niess/python-appimage/pull/49)). Please note, + however, that this involves directly copying the local package, which has + several limitations. {{ begin(".capsule") }} ### Entry point script {% raw %} -The entry point script deserves some additional explanations. This script allows -to customize the startup of your application. A typical `entrypoint.sh` script -would look like +The entry point script deserves some additional explanations. This script lets +you customise your application's startup. A typical `entrypoint.sh` script would +look like this ```bash {{ python-executable }} ${APPDIR}/opt/python{{ python-version }}/bin/my_app.py "$@" ``` -where `my_app.py` is the application startup script, installed by `pip`. As can -be seen from the previous example, the `entrypoint.sh` script recognises some -particular variables, nested between double curly braces, `{{ }}`. Those -variables are listed in the table hereafter. In addition, usual [AppImage -environement variables][APPIMAGE_ENV] can be used as well, if needed. For -example, `$APPDIR` points to the AppImage mount point at runtime. +where `my_app.py` is the application startup script installed by `pip`. As can +be seen from the previous example, the `entrypoint.sh` script recognises +particular variables nested between double curly braces (`{{}}`). These +variables are listed in the table below. In addition, the usual [AppImage +environement variables][APPIMAGE_ENV] can be used if needed. For instance, +`$APPDIR` points to the AppImage mount point at runtime. {% endraw %} + | variable | Description | |----------------------|---------------------------------------------------------------| | `architecture` | The AppImage architecture, e.g. `x86_64`. | @@ -173,20 +185,20 @@ example, `$APPDIR` points to the AppImage mount point at runtime. {% raw %} !!! Note - By default, Python AppImages are not isolated from the user space, nor from - Python specific environment variables, the like `PYTHONPATH`. Depending on - your use case, this can be problematic. + By default, Python AppImages are not isolated from user space or + Python-specific environment variables such as `PYTHONPATH`. Depending on + your use case, this can cause problems. - The runtime isolation level can be changed by adding the `-E`, `-s` or `-I` - options, when invoking the runtime. For example, - `{{ python-executable }} -I` starts a fully isolated Python instance. + You can change the isolation level by adding the `-E`, `-s` or `-I` options + when invoking the runtime. For example, `{{ python-executable }} -I` starts + a fully isolated Python instance. {% endraw %} ### Bundling data files -`python-appimage` is also capable of bundling in auxilliary data files directly -into the resulting AppImage. `-x/--extra-data` switch exists for that task. -Consider following example. +`python-appimage` is also capable of bundling auxiliary data files directly into +the resulting AppImage. The `-x/--extra-data` switch is used for this purpose. +Consider the following example. ```bash echo -n "foo" > foo @@ -195,10 +207,10 @@ echo -n "baz" > bar/baz python-appimage [your regular parameters] -x foo bar/* ``` -User data included in such a way becomes accessible to the Python code -contained within the AppImage in a form of regular files under the directory -pointed to by `APPDIR` environment variable. Example of Python 3 script -that reads these exemplary files is presented below. +In this way, user data becomes accessible to the Python code contained within +the AppImage as regular files under the directory pointed to by the `APPDIR` +environment variable. An example of a Python 3 script that reads these files is +presented below. ```python import os, pathlib @@ -206,7 +218,7 @@ for fileName in ("foo", "baz"): print((pathlib.Path(os.getenv("APPDIR")) / fileName).read_text()) ``` -Above code, when executed, would print following output. +When executed, the above code would produce the following output. ```bash foo @@ -215,37 +227,36 @@ baz ## Advanced packaging -In more complex cases, e.g. if your application relies on external C libraries -not bundled with the Python runtime, then the simple packaging scheme described -previously will fail. Indeed, this falls out of the scope of `python-appimage`, -whose main purpose it to relocate an existing Python install. In this case, you -might rather refer to the initial AppImage [Packaging -Guide][APPIMAGE_PACKAGING], and use alternative tools like +In more complex cases, for example if your application relies on external C +libraries that are not bundled with the Python runtime, the simple packaging +scheme described previously will not work. This falls outside the scope of +`python-appimage`, which is primarily intended for relocating an existing Python +installation. In this case, you may wish to refer to the initial AppImage +[Packaging Guide][APPIMAGE_PACKAGING], and use alternative tools such as [linuxdeploy][LINUXDEPLOY]. -However, `python-appimage` can still be of use in more complex cases by -extracting its AppImages to an AppDir, as discussed in the [Advanced -installation](index.md#advanced-installation) section. The extracted AppImages -contain a relocatable Python runtime, that can be used as a starting base for -building more complex AppImages. +However, `python-appimage` can still be useful in more complex cases, as it can +generate a base AppDir containing a relocatable Python runtime (e.g., using the +`-n` option). This can then serve as a starting point to create more complex +AppImages. !!! Tip - In some cases, a simple workaround to missing external libraries can be to - fetch portable versions of those from a Manylinux distro, and to bundle them - under `AppDir/usr/lib`. You might also need to edit their dynamic section, - e.g. using [`patchelf`][PATCHELF], which is installed by `python-appimage`. + In some cases, a simple workaround for missing external libraries is to + download portable versions of them from a Manylinux distribution and bundle + them in `AppDir/usr/lib`. You may also need to edit the dynamic section + using [`patchelf`][PATCHELF], which is installed by `python-appimage`. {{ begin(".capsule") }} ### C extension modules -If your application relies on C extension modules, they need to be compiled on a -Manylinux distro in order to be portable. In addition, their dependencies need -to be bundled as well. In this case, you might better start by building a binary -wheel of your package, using tools like [Auditwheel][AUDITWHEEL] which can -automate some parts of the packaging process. Note that `auditwheel` is already +If your application relies on C extension modules, these must be compiled on a +Manylinux distribution in order to be portable. Their dependencies also need to +be bundled. In this case, it would be better to start by building a binary wheel +of your package using tools like [Auditwheel][AUDITWHEEL], which can automate +some parts of the packaging process. Please note that `auditwheel` is already installed on the Manylinux Docker images. -Once you have built a binary wheel of your package, it can be used with -`python-appimage` in order to package your application as an AppImage. +Once you have built a binary wheel of your package, you can use it with +`python-appimage` to package your application as an AppImage. {{ end(".capsule") }} diff --git a/docs/src/index.md b/docs/src/index.md index 91c9653..68db225 100644 --- a/docs/src/index.md +++ b/docs/src/index.md @@ -15,8 +15,8 @@ # Python AppImages We provide relocatable Python runtimes for _Linux_ systems, as -[AppImages][APPIMAGE]. These runtimes have been extracted from -[manylinux][MANYLINUX] Docker images. +[AppImages][APPIMAGE]. These runtimes have been extracted from a variety of +[Manylinux][MANYLINUX] Docker images. {{ "" | id("append-releases-list") }} ## Basic installation @@ -35,23 +35,24 @@ chmod +x python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage !!! Note As can be seen from the previous [example](#basic-installation-example), the - AppImage name contains several informations. That are, the Python full - version ({{ "3.10.2" | id("example-full-version") }}), the CPython tag - ({{ "cp310-cp310" | id("example-python-tag") }}), the Linux compatibility - tag ({{ "manylinux2014" | id("example-linux-tag") }}) and the machine - architecture ({{ "x86_64" | id("example-arch-tag") }}). + AppImage name contains several pieces of information. This includes the + Python full version ({{ "3.10.2" | id("example-full-version") }}), the + [CPython tag][PEP_425] ({{ "cp310-cp310" | id("example-python-tag") }}), the + [Linux compatibility tag][MANYLINUX] ({{ "manylinux2014" | + id("example-linux-tag") }}) and the machine architecture ({{ "x86_64" | + id("example-arch-tag") }}). !!! Caution - One needs to **select an AppImage** that matches **system requirements**. A - summmary of available Python AppImages is provided at the - [bottom](#available-python-appimages) of this page. + It is essential to **select an AppImage** that aligns with the **system's + specifications**. An overview of the available Python AppImages is provided + at the [bottom](#available-python-appimages) of this page. {{ begin(".capsule") }} ### Creating a symbolic link -Since AppImages native names are rather lengthy, one might create a symbolic -link, e.g. as +As AppImages' native names are quite lengthy, it might be relevant to create a +symbolic link, for example as {{ begin("#basic-installation-example-symlink") }} ```bash @@ -59,23 +60,23 @@ ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppImage python3.10 ``` {{ end("#basic-installation-example-symlink") }} -Then, executing the AppImage as -{{ "`./python3.10`" | id("basic-installation-example-execution") }} should -start a Python interactive session on _almost_ any Linux, provided that **fuse** -is supported. +Executing the AppImage as {{ "`./python3.10`" | +id("basic-installation-example-execution") }} should then start a Python +interactive session on almost any Linux distribution, provided that **fuse** is +supported. {{ end(".capsule") }} !!! Tip - Fuse is not supported on Windows Subsytem for Linux v1 (WSL1), preventing - AppImages direct execution. Yet, one can still extract the content of Python - AppImages and use them, as explained in the [Advanced - installation](#advanced-installation) section. + Fuse is not supported on Windows Subsystem for Linux v1 (WSL1), which + prevents the direct execution of AppImages. However, it is still possible to + extract the contents of Python AppImages and use them, as explained in the + [Advanced installation](#advanced-installation) section. ## Installing site packages -Site packages can be installed using `pip`, distributed with the AppImage. For -example, the following +Site packages can be installed using `pip`, which is distributed with Python +AppImages. For example, the following command {{ begin("#site-packages-example") }} ```bash @@ -83,23 +84,22 @@ example, the following ``` {{ end("#site-packages-example") }} -installs the numpy package, where it is assumed that a symlink to the AppImage -has been previously created. When using the **basic installation** scheme, by -default Python packages are installed to your **user space**, i.e. under -`~/.local` on Linux. +installs the [numpy][NUMPY] package, assuming that a symlink to the AppImage has +been created beforehand. When using this **basic installation** scheme, Python +packages are installed by default to your **user space** (i.e. under `~/.local` +on Linux). !!! Note - AppImage are read-only. Therefore, site packages cannot be directly - installed to the AppImage. However, the AppImage can be extracted, as + AppImages are read-only. Therefore, site packages cannot be installed + directly to the Python AppImage. However, the AppImage can be extracted, as explained in the [Advanced installation](#advanced-installation) section. {{ begin(".capsule") }} ### Alternative site packages location -One can -specify an alternative installation directory for site packages using the -`--target` option of pip. For example, the following +The `--target option` of pip can be used to specify an alternative installation +directory for site packages. For example, the following command {{ begin("#site-packages-example-target") }} ```bash @@ -107,7 +107,9 @@ specify an alternative installation directory for site packages using the ``` {{ end("#site-packages-example-target") }} -installs the numpy package besides the AppImage, in a `packages` folder. +installs the [numpy][NUMPY] package in the `packages` folder, besides the +AppImage. + {{ end(".capsule") }} !!! Tip @@ -116,33 +118,33 @@ installs the numpy package besides the AppImage, in a `packages` folder. `PYTHONPATH` environment variable. !!! Caution - While Python AppImages are relocatable, site packages might not be. In - particular, packages installing executable Python scripts assume a fix - location of the Python runtime. If the Python AppImage is moved, then these - scripts will fail. This can be patched by editing the script - [shebang][SHEBANG], or be reinstalling the corresponding package. + Although Python AppImages are relocatable, site packages may not be. In + particular, packages that install executable Python scripts assume a fixed + location for the Python runtime. If the Python AppImage is moved, these + scripts will fail. This can be resolved by either editing the script + [shebang][SHEBANG] or reinstalling the corresponding package. ## Isolating from the user environment By default, Python AppImages are not isolated from the user environment. For example, packages located under `~/.local/lib/pythonX.Y/site-packages` are -loaded prior to AppImage's (system) ones. Note that this is the usual Python -runtime behaviour. However, it can be conflictual for some applications. +loaded before the AppImage's ones. Note that this is the standard Python runtime +behaviour. However, this can be conflictual for some applications. -In order to isolate your application from the user environment, the Python -runtime provides the `-E`, `-s` and `-I` options. For example, invoking a Python -AppImage as {{ "`./python3.10 -s`" | id("user-isolation-example") }} prevents -the loading of user site packages (located under `~/.local`). Additionaly, the -`-E` option disables Python related environment variables. In particular, it -prevents packages under `PYTHONPATH` to be loaded. The `-I` option triggers both -`-E` and `-s`. +To isolate your application from the user environment, the Python runtime +provides the `-E`, `-s` and `-I` options. For example, running {{ "`./python3.10 +-s`" | id("user-isolation-example") }} prevents the loading of user site +packages located under `~/.local`. Additionally, the `-E` option disables +Python-related environment variables. In particular, it prevents packages under +`PYTHONPATH` from being loaded. The `-I` option triggers both the `-E` and `-s` +options. ## Using a virtual environement -Isolation can also be achieved with a [virtual environment][VENV]. Python -AppImages can create a `venv` using the standard syntax, e.g. as +[Virtual environments][VENV] can also be used to achieve isolation. For example, +Python AppImages can create a `venv` using the standard syntax, as {{ begin("#venv-example") }} ```bash @@ -150,15 +152,16 @@ AppImages can create a `venv` using the standard syntax, e.g. as ``` {{ end("#venv-example") }} -Note that moving the base Python AppImage to another location breaks the virtual -environment. This can be patched by editing symbolic links under `venv/bin`, as -well as the `home` variable in `venv/pyvenv.cfg`. The latter must point to the -AppImage directory. +Please note that moving the base Python AppImage to a different location will +break the virtual environment. This can be resolved by editing the symbolic +links in `venv/bin`, as well as the `home` variable in `venv/pyvenv.cfg`. The +latter must point to the AppImage directory. !!! Tip - Old Python AppImages, created before version 1.1, fail setting up `pip` - automaticaly during `venv` creation. However, this can be patched by calling - `ensurepip` from within the `venv`, after its creation. For example, as + Old Python AppImages created before version 1.1 fail to set up `pip` + automatically during `venv` creation. However, this can be resolved by + calling `ensurepip` within the virtual environment after its creation. For + example, as ```bash source /path/to/new/virtual/environment/bin/activate @@ -170,10 +173,10 @@ python -m ensurepip ## Advanced installation The [basic installation](#basic-installation) scheme described previously has -some limitations when using Python AppImages as a runtime. For example, site -packages need to be installed to a separate location. This can be solved by -extracting a Python AppImage to an `*.AppDir` directory, e.g. as - +certain limitations when Python AppImages are used as the runtime environment. +For example, site packages need to be installed in a different location. This +issue can be resolved by extracting a Python AppImage to an `AppDir` +directory, e.g. as {{ begin("#advanced-installation-example") }} ```bash @@ -185,32 +188,32 @@ ln -s python3.10.2-cp310-cp310-manylinux2014_x86_64.AppDir/AppRun python3.10 ``` {{ end("#advanced-installation-example") }} -Then, by default **site packages** are installed to the extracted **AppDir**, -when using `pip`. In addition, executable scripts installed by `pip` are patched -in order to use relative [shebangs][SHEBANG]. Consequently, the AppDir can be -freely moved around. +Then, by default, **site packages** are installed to the extracted `AppDir` +when using `pip`. Additionally, executable scripts installed by `pip` are +patched to use relative [shebangs][SHEBANG]. Consequently, the `AppDir` can be +moved around freely. !!! Note - Python AppDirs follow the [manylinux][MANYLINUX] installation scheme. - Executable scripts are installed under `AppDir/opt/pythonX.Y/bin` where _X_ - and _Y_ in _pythonX.Y_ stand for the major and minor version numbers. Site - packages are located under - `AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`. For convenience, `pip` - installed applications are also mirrored under `AppDir/usr/bin`, using - symbolic links. + Python `AppDirs` follow the [Manylinux][MANYLINUX] installation scheme. + Executable scripts are installed under the `AppDir/opt/pythonX.Y/bin` + directory, where _X_ and _Y_ represent the major and minor version numbers, + respectively. Site packages are located under + `AppDir/opt/pythonX.Y/lib/pythonX.Y/site-packages`. For convenience, + applications installed using `pip` are also mirrored under `AppDir/usr/bin` + using symbolic links. !!! Tip - As for Python AppImages, by default the extracted runtime is [not isolated - from the user environment](#isolating-from-the-user-environment). This + As for Python AppImages, the extracted runtime is [not isolated from the + user environment](#isolating-from-the-user-environment) by default. This behaviour can be changed by editing the `AppDir/usr/bin/pythonX.Y` wrapper - script, and by adding the `-s`, `-E` or `-I` option at the very bottom, - where Python is invoked. + script and adding the `-s`, `-E` or `-I` option to the line invoking Python + (at the end of the script). {{ begin(".capsule") }} ### Repackaging the AppImage -An extracted AppDir can be re-packaged as an AppImage using +An extracted `AppDir` can be re-packaged as an AppImage using [appimagetool][APPIMAGETOOL], e.g. as @@ -227,21 +230,21 @@ chmod +x appimagetool-x86_64.AppImage ``` {{ end("#repackaging-example") }} -This allows to customize your Python AppImage, for example by adding your -preferred site packages. +This allows you to personalise your Python AppImage by adding your preferred +site packages, for example. {{ end(".capsule") }} !!! Note - Python AppImages can also be used for packaging Python based applications, - as AppImages. Additional details are provided in the [developers + Python AppImages can also be used to package Python-based applications as + AppImages. Further information can be found in the [developers' section](apps). ## Available Python AppImages -A summary of available Python AppImages [releases][RELEASES] is provided in the -[table](#appimages-download-links) below. Clicking on a badge should download -the corresponding AppImage. +The [table](#appimages-download-links) below provides a summary of the available +Python AppImage [releases][RELEASES]. Clicking on a badge should download the +corresponding AppImage. {{ begin("#suggest-appimage-download") }} !!! Caution diff --git a/docs/src/js/index.js b/docs/src/js/index.js index 79c5e5e..6e5f990 100644 --- a/docs/src/js/index.js +++ b/docs/src/js/index.js @@ -75,7 +75,7 @@ $.getJSON("https://api.github.com/repos/niess/python-appimage/releases").done(fu elements.push(`${release.version}`) } $("#append-releases-list").html( - " Available Python versions are " + + " The available Python versions are " + elements.slice(0, -1).join(", ") + " and " + elements[elements.length - 1] +