| Name | myst-libre JSON |
| Version |
0.2.9
JSON |
| download |
| home_page | None |
| Summary | A Python library for managing source code repositories, interacting with Docker registries, handling MyST markdown operations, and spawning JupyterHub instances locally. |
| upload_time | 2024-12-19 18:02:12 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2024 Agah Karakuzu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
myst
docker
jupyterhub
markdown
repository
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MyST Libre
&color=white)
Following the [REES](https://repo2docker.readthedocs.io/en/latest/specification.html), `myst-libre` streamlines building [✨MyST articles✨](https://mystmd.org/) in containers.
* A repository containing MyST sources
* A Docker image (built by [`binderhub`](https://github.com/jupyterhub/binderhub)) in a public (or private) registry, including:
* Dependencies to execute notebooks/markdown files in the MyST repository
* JupyterHub (typically part of images built by `binderhub`)
* Input data required by the executable content (optional)
Given these resources, myst-libre starts a Docker container, mounts the MyST repository and data (if available), and builds a MyST publication.
> [!NOTE]
> This project was started to support publishing MyST articles as living preprints on [`NeuroLibre`](https://neurolibre.org).
## Installation
### External dependencies
> [!IMPORTANT]
> Ensure the following prerequisites are installed:
- Node.js (For MyST) [installation guide](https://mystmd.org/guide/installing-prerequisites)
- Docker [installation guide](https://docs.docker.com/get-docker/)
### Install myst-libre
```
pip install myst-libre
```
**Set up environment variables:**
If you are using a private image registry, create a `.env` file in the project root and add the following:
```env
DOCKER_PRIVATE_REGISTRY_USERNAME=your_username
DOCKER_PRIVATE_REGISTRY_PASSWORD=your_password
```
## Quick Start
**Import libraries and define REES resources**
```python
from myst_libre.tools import JupyterHubLocalSpawner, MystMD
from myst_libre.rees import REES
from myst_libre.builders import MystBuilder
rees_resources = REES(dict(
registry_url="https://your-registry.io",
gh_user_repo_name = "owner/repository",
gh_repo_commit_hash = "full_SHA_commit_A",
binder_image_tag = "full_SHA_commit_A_or_B",
dotenv = '/path/to/dotenv'))
```
> [!NOTE]
> Currently, the assumption is that the Docker image was built by binderhub from a REES-compliant repository that also includes the MyST content. Therefore, `binder_image_tag` and `gh_repo_commit_hash` are simply two different commits in the same (`gh_repo_user_name`) repository. However, `binder_image_tag` is not allowed to be ahead of `gh_repo_commit_hash`.
**Fetch resources and spawn JupyterHub in the respective container**
```python
hub = JupyterHubLocalSpawner(rees_resources,
host_build_source_parent_dir = '/tmp/myst_repos',
container_build_source_mount_dir = '/home/jovyan', #default
host_data_parent_dir = "/tmp/myst_data", #optional
container_data_mount_dir = '/home/jovyan/data', #optional
)
hub.spawn_jupyter_hub()
```
* MyST repository will be cloned at:
```
tmp/
└── myst_repos/
└── owner/
└── repository/
└── full_commit_SHA_A/
├── myst.yml
├── _toc.yml
├── binder/
│ ├── requirements.txt (or other REES dependencies)
│ └── data_requirement.json (optional)
├── content/
│ ├── my_notebook.ipynb
│ └── my_myst_markdown.md
├── paper.md
└── paper.bib
```
Repository will be mounted to the container as `/tmp/myst_repos/owner/repository/full_commit_SHA_A:/home/jovyan`.
* If a [`repo2data`](https://github.com/SIMEXP/Repo2Data) manifest is found in the repository, the data will be downloaded to and cached at:
```
tmp/
└── myst_data/
└── my-dataset
```
otherwise, it can be manually defined for an existing data under `/tmp/myst_data` as follows:
```
rees_resources.dataset_name = "my-dataset"
```
In either case, data will be mounted as `/tmp/myst_data/my-dataset:/home/jovyan/data/my-dataset`. If no data is provided, this step will be skipped.
**Build your MyST article**
```python
MystBuilder(hub).build()
```
**Check out the built document**
In your terminal:
```
npx serve /tmp/myst_repos/owner/repository/full_commit_SHA_A/_build/html
```
Visit ✨`http://localhost:3000`✨.
## Table of Contents
- [Myst Libre](#myst-libre)
- [Table of Contents](#table-of-contents)
- [Installation](#installation)
- [Usage](#usage)
- [Authentication](#authentication)
- [Docker Registry Client](#docker-registry-client)
- [Build Source Manager](#build-source-manager)
- [JupyterHub Local Spawner](#jupyterhub-local-spawner)
- [MyST Markdown Client](#myst-markdown-client)
- [Module and Class Descriptions](#module-and-class-descriptions)
- [Contributing](#contributing)
- [License](#license)
## Usage
### Authentication
The `Authenticator` class handles loading authentication credentials from environment variables.
```python
from myst_libre.tools.authenticator import Authenticator
auth = Authenticator()
print(auth._auth)
```
### Docker Registry Client
The DockerRegistryClient class provides methods to interact with a Docker registry.
```python
from myst_libre.tools.docker_registry_client import DockerRegistryClient
client = DockerRegistryClient(registry_url='https://my-registry.example.com', gh_user_repo_name='user/repo')
token = client.get_token()
print(token)
```
### Build Source Manager
The BuildSourceManager class manages source code repositories.
```python
from myst_libre.tools.build_source_manager import BuildSourceManager
manager = BuildSourceManager(gh_user_repo_name='user/repo', gh_repo_commit_hash='commit_hash')
manager.git_clone_repo('/path/to/clone')
project_name = manager.get_project_name()
print(project_name)
```
## Module and Class Descriptions
### AbstractClass
**Description**: Provides basic logging functionality and colored printing capabilities.
### Authenticator
**Description**: Handles authentication by loading credentials from environment variables.
**Inherited from**: AbstractClass
**Inputs**: Environment variables `DOCKER_PRIVATE_REGISTRY_USERNAME` and `DOCKER_PRIVATE_REGISTRY_PASSWORD`
### RestClient
**Description**: Provides a client for making REST API calls.
**Inherited from**: Authenticator
### DockerRegistryClient
**Description**: Manages interactions with a Docker registry.
**Inherited from**: Authenticator
**Inputs**:
- `registry_url`: URL of the Docker registry
- `gh_user_repo_name`: GitHub user/repository name
- `auth`: Authentication credentials
### BuildSourceManager
**Description**: Manages source code repositories.
**Inherited from**: AbstractClass
**Inputs**:
- `gh_user_repo_name`: GitHub user/repository name
- `gh_repo_commit_hash`: Commit hash of the repository
### JupyterHubLocalSpawner
**Description**: Manages JupyterHub instances locally.
**Inherited from**: AbstractClass
**Inputs**:
- `rees`: Instance of the REES class
- `registry_url`: URL of the Docker registry
- `gh_user_repo_name`: GitHub user/repository name
- `auth`: Authentication credentials
- `binder_image_tag`: Docker image tag
- `build_src_commit_hash`: Commit hash of the repository
- `container_data_mount_dir`: Directory to mount data in the container
- `container_build_source_mount_dir`: Directory to mount build source in the container
- `host_data_parent_dir`: Host directory for data
- `host_build_source_parent_dir`: Host directory for build source
### MystMD
**Description**: Manages MyST markdown operations such as building and converting files.
**Inherited from**: AbstractClass
**Inputs**:
- `build_dir`: Directory where the build will take place
- `env_vars`: Environment variables needed for the build process
- `executable`: Name of the MyST executable (default is 'myst')
Raw data
{
"_id": null,
"home_page": null,
"name": "myst-libre",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "myst, docker, jupyterhub, markdown, repository",
"author": null,
"author_email": "agahkarakuzu <agahkarakuzu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/13/75/1ae3420fc07c69c0473b840c07ff1ca687209dde0a566f63ee786c987f69/myst_libre-0.2.9.tar.gz",
"platform": null,
"description": "\n# MyST Libre\n\n&color=white)\n\nFollowing the [REES](https://repo2docker.readthedocs.io/en/latest/specification.html), `myst-libre` streamlines building [\u2728MyST articles\u2728](https://mystmd.org/) in containers.\n\n* A repository containing MyST sources\n* A Docker image (built by [`binderhub`](https://github.com/jupyterhub/binderhub)) in a public (or private) registry, including:\n * Dependencies to execute notebooks/markdown files in the MyST repository\n * JupyterHub (typically part of images built by `binderhub`)\n* Input data required by the executable content (optional)\n\nGiven these resources, myst-libre starts a Docker container, mounts the MyST repository and data (if available), and builds a MyST publication.\n\n> [!NOTE]\n> This project was started to support publishing MyST articles as living preprints on [`NeuroLibre`](https://neurolibre.org).\n\n## Installation\n\n### External dependencies \n\n> [!IMPORTANT]\n> Ensure the following prerequisites are installed:\n\n- Node.js (For MyST) [installation guide](https://mystmd.org/guide/installing-prerequisites)\n- Docker [installation guide](https://docs.docker.com/get-docker/)\n\n### Install myst-libre\n\n```\npip install myst-libre\n```\n\n**Set up environment variables:**\n\nIf you are using a private image registry, create a `.env` file in the project root and add the following:\n\n```env\nDOCKER_PRIVATE_REGISTRY_USERNAME=your_username\nDOCKER_PRIVATE_REGISTRY_PASSWORD=your_password\n```\n\n## Quick Start\n\n**Import libraries and define REES resources**\n\n```python\nfrom myst_libre.tools import JupyterHubLocalSpawner, MystMD\nfrom myst_libre.rees import REES\nfrom myst_libre.builders import MystBuilder\n\nrees_resources = REES(dict(\n registry_url=\"https://your-registry.io\",\n gh_user_repo_name = \"owner/repository\",\n gh_repo_commit_hash = \"full_SHA_commit_A\",\n binder_image_tag = \"full_SHA_commit_A_or_B\",\n dotenv = '/path/to/dotenv'))\n```\n\n> [!NOTE]\n> Currently, the assumption is that the Docker image was built by binderhub from a REES-compliant repository that also includes the MyST content. Therefore, `binder_image_tag` and `gh_repo_commit_hash` are simply two different commits in the same (`gh_repo_user_name`) repository. However, `binder_image_tag` is not allowed to be ahead of `gh_repo_commit_hash`.\n\n**Fetch resources and spawn JupyterHub in the respective container**\n\n```python\nhub = JupyterHubLocalSpawner(rees_resources,\n host_build_source_parent_dir = '/tmp/myst_repos',\n container_build_source_mount_dir = '/home/jovyan', #default\n host_data_parent_dir = \"/tmp/myst_data\", #optional\n container_data_mount_dir = '/home/jovyan/data', #optional\n )\nhub.spawn_jupyter_hub()\n```\n\n* MyST repository will be cloned at:\n\n```\ntmp/\n\u2514\u2500\u2500 myst_repos/\n \u2514\u2500\u2500 owner/\n \u2514\u2500\u2500 repository/\n \u2514\u2500\u2500 full_commit_SHA_A/\n \u251c\u2500\u2500 myst.yml\n \u251c\u2500\u2500 _toc.yml\n \u251c\u2500\u2500 binder/\n \u2502 \u251c\u2500\u2500 requirements.txt (or other REES dependencies)\n \u2502 \u2514\u2500\u2500 data_requirement.json (optional)\n \u251c\u2500\u2500 content/\n \u2502 \u251c\u2500\u2500 my_notebook.ipynb\n \u2502 \u2514\u2500\u2500 my_myst_markdown.md\n \u251c\u2500\u2500 paper.md\n \u2514\u2500\u2500 paper.bib\n```\n\nRepository will be mounted to the container as `/tmp/myst_repos/owner/repository/full_commit_SHA_A:/home/jovyan`.\n\n* If a [`repo2data`](https://github.com/SIMEXP/Repo2Data) manifest is found in the repository, the data will be downloaded to and cached at:\n\n```\ntmp/\n\u2514\u2500\u2500 myst_data/\n \u2514\u2500\u2500 my-dataset\n```\n\notherwise, it can be manually defined for an existing data under `/tmp/myst_data` as follows:\n\n```\nrees_resources.dataset_name = \"my-dataset\"\n```\n\nIn either case, data will be mounted as `/tmp/myst_data/my-dataset:/home/jovyan/data/my-dataset`. If no data is provided, this step will be skipped.\n\n**Build your MyST article**\n\n```python\nMystBuilder(hub).build()\n```\n\n**Check out the built document**\n\nIn your terminal:\n\n```\nnpx serve /tmp/myst_repos/owner/repository/full_commit_SHA_A/_build/html\n```\n\nVisit \u2728`http://localhost:3000`\u2728.\n\n## Table of Contents\n\n- [Myst Libre](#myst-libre)\n - [Table of Contents](#table-of-contents)\n - [Installation](#installation)\n - [Usage](#usage)\n - [Authentication](#authentication)\n - [Docker Registry Client](#docker-registry-client)\n - [Build Source Manager](#build-source-manager)\n - [JupyterHub Local Spawner](#jupyterhub-local-spawner)\n - [MyST Markdown Client](#myst-markdown-client)\n - [Module and Class Descriptions](#module-and-class-descriptions)\n - [Contributing](#contributing)\n - [License](#license)\n\n## Usage\n\n### Authentication\n\nThe `Authenticator` class handles loading authentication credentials from environment variables.\n\n```python\nfrom myst_libre.tools.authenticator import Authenticator\n\nauth = Authenticator()\nprint(auth._auth)\n```\n\n\n### Docker Registry Client\n\nThe DockerRegistryClient class provides methods to interact with a Docker registry.\n\n```python\nfrom myst_libre.tools.docker_registry_client import DockerRegistryClient\n\nclient = DockerRegistryClient(registry_url='https://my-registry.example.com', gh_user_repo_name='user/repo')\ntoken = client.get_token()\nprint(token)\n```\n\n### Build Source Manager\n\nThe BuildSourceManager class manages source code repositories.\n\n```python\nfrom myst_libre.tools.build_source_manager import BuildSourceManager\n\nmanager = BuildSourceManager(gh_user_repo_name='user/repo', gh_repo_commit_hash='commit_hash')\nmanager.git_clone_repo('/path/to/clone')\nproject_name = manager.get_project_name()\nprint(project_name)\n```\n\n## Module and Class Descriptions\n\n### AbstractClass\n**Description**: Provides basic logging functionality and colored printing capabilities.\n\n### Authenticator\n**Description**: Handles authentication by loading credentials from environment variables. \n**Inherited from**: AbstractClass \n**Inputs**: Environment variables `DOCKER_PRIVATE_REGISTRY_USERNAME` and `DOCKER_PRIVATE_REGISTRY_PASSWORD`\n\n### RestClient\n**Description**: Provides a client for making REST API calls. \n**Inherited from**: Authenticator\n\n### DockerRegistryClient\n**Description**: Manages interactions with a Docker registry. \n**Inherited from**: Authenticator \n**Inputs**:\n- `registry_url`: URL of the Docker registry\n- `gh_user_repo_name`: GitHub user/repository name\n- `auth`: Authentication credentials\n\n### BuildSourceManager\n**Description**: Manages source code repositories. \n**Inherited from**: AbstractClass \n**Inputs**:\n- `gh_user_repo_name`: GitHub user/repository name\n- `gh_repo_commit_hash`: Commit hash of the repository\n\n### JupyterHubLocalSpawner\n**Description**: Manages JupyterHub instances locally. \n**Inherited from**: AbstractClass \n**Inputs**:\n- `rees`: Instance of the REES class\n- `registry_url`: URL of the Docker registry\n- `gh_user_repo_name`: GitHub user/repository name\n- `auth`: Authentication credentials\n- `binder_image_tag`: Docker image tag\n- `build_src_commit_hash`: Commit hash of the repository\n- `container_data_mount_dir`: Directory to mount data in the container\n- `container_build_source_mount_dir`: Directory to mount build source in the container\n- `host_data_parent_dir`: Host directory for data\n- `host_build_source_parent_dir`: Host directory for build source\n\n### MystMD\n**Description**: Manages MyST markdown operations such as building and converting files. \n**Inherited from**: AbstractClass \n**Inputs**:\n- `build_dir`: Directory where the build will take place\n- `env_vars`: Environment variables needed for the build process\n- `executable`: Name of the MyST executable (default is 'myst')\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 Agah Karakuzu Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A Python library for managing source code repositories, interacting with Docker registries, handling MyST markdown operations, and spawning JupyterHub instances locally.",
"version": "0.2.9",
"project_urls": {
"Homepage": "https://github.com/agahkarakuzu/myst_libre"
},
"split_keywords": [
"myst",
" docker",
" jupyterhub",
" markdown",
" repository"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3538a554077069d96b9f27c476b8c9aece4513f750b70dce778da6c97bad4b51",
"md5": "56397e0cf6f6ecd1c0eaedf886bef9aa",
"sha256": "ca45949b00c1a732b98c6d90fe409a61746cb9e4d555b19ab28e8a12af7684a0"
},
"downloads": -1,
"filename": "myst_libre-0.2.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "56397e0cf6f6ecd1c0eaedf886bef9aa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 19742,
"upload_time": "2024-12-19T18:02:11",
"upload_time_iso_8601": "2024-12-19T18:02:11.227249Z",
"url": "https://files.pythonhosted.org/packages/35/38/a554077069d96b9f27c476b8c9aece4513f750b70dce778da6c97bad4b51/myst_libre-0.2.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "13751ae3420fc07c69c0473b840c07ff1ca687209dde0a566f63ee786c987f69",
"md5": "044cca0f864ddbf5c7a80e4f7524d683",
"sha256": "4cc7ff0f93104299ba57b3980954a1edd50da8cf8eefe55155a21a4583fc7406"
},
"downloads": -1,
"filename": "myst_libre-0.2.9.tar.gz",
"has_sig": false,
"md5_digest": "044cca0f864ddbf5c7a80e4f7524d683",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 20157,
"upload_time": "2024-12-19T18:02:12",
"upload_time_iso_8601": "2024-12-19T18:02:12.594146Z",
"url": "https://files.pythonhosted.org/packages/13/75/1ae3420fc07c69c0473b840c07ff1ca687209dde0a566f63ee786c987f69/myst_libre-0.2.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-19 18:02:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "agahkarakuzu",
"github_project": "myst_libre",
"github_not_found": true,
"lcname": "myst-libre"
}
