Metadata-Version: 2.1
Name: gsmo
Version: 0.0.2
Summary: Commonsense Jupyter/Docker/Git integrations.
Home-page: https://github.com/runsascoded/gsmo
Author: Ryan Williams
Author-email: ryan@runsascoded.com
License: UNKNOWN
Description: # gsmo
        Commonsense Jupyter/Docker/Git integrations.
        - mount current directory into a Docker container
            - pass through Git configs so that commits in the Docker container exist outside it (with correct permissions)
            - easily configure Python/Linux environment inside container (see [`gsmo.yml`])
        - run a notebook or script [non-interactively](#non-interactive) (and commit results), or [boot a Jupyter server](#jupyter-server) or [Bash shell](#bash-shell) for interactive work
        
        ## Usage
        
        ### Non-interactive (`run.ipynb`) <a id="non-interactive"></a>
        `gsmo` helps run notebooks and scripts in a reproducible fashion (inside Docker containers), and pass-through changes (especially Git commits) to the host machine:
        
        Running:
        ```bash
        gsmo
        ```
        in a project directory will:
        - load configs ([`gsmo.yml`])
        - build a Docker image
        - run a container from that image
        - run the project's `run.ipynb` notebook inside that container
        - Git-commit results  
        
        ### Interactive <a id="interactive"></a>
        
        #### Jupyter Server <a id="jupyter-server"></a>
        Build a Docker image from the current directory, and launch a Jupyter server with the current directory mounted (and various Git- and OS-level configs set, so that changes/commits are reflected on the host machine): 
        ```bash
        gsmo -j
        ```
        - runs at a "random" but stable port derived from a hash of the module name
        - easily configure Python/Linux environment using [`gsmo.yml`]
        
        #### Bash shell <a id="bash-shell"></a>
        Build a Docker image from the current directory, and launch a Bash shell with it mounted (and various Git- and OS-level configs set, so that changes/commits are reflected on the host machine): 
        ```bash
        gsmo -s
        ```
        
        ## Module configuration: 
        
        ### `gsmo.yml` <a id="gsmo-yml"></a>
        When you run `gsmo` in a directory, it will look for a `gsmo.yml` file in the current directory with any of the following fields and build a corresponding Docker image:
        
        - `name` (`str`; default: project directory's basename): module name; also used as repository for built Docker image
        - `pip` (`str` or `List[str]`): `pip` libraries to install
        - `apt` (`str` or `List[str]`): `apt` libraries to install
        - `env` (`str` or `List[str]`): environment variables to set
        - `group` (`str` or `List[str]`): OS groups to add to the user inside the container
          - paths are accepted, in which case the group that owns that path will be used
        - `tag` (`str` or `List[str]`): additional Docker tags within `name` repository
        - `mount` (`str` or `List[str]`): Docker mounts, in several convenient formats:
          - `<path>`: equivalent to `<path>:/<path>`; easily pass local project subdirectories into Docker container, e.g. `home/.bashrc`, `etc/pip.conf`, etc.
          - standard Docker `<src>:<dst>` syntax is also supported
          - in all cases, `~` and env vars are expanded 
        - `image` (`str`; default: `runsascoded/gsmo`): base Docker image to build from
        - `commit` (`str` or `List[str]`; default: `out` config dir): paths to Git commit after a run (in non-interactive mode)
        - `root` (`bool`; default `False`)
          - when set, run as `root` inside container
          - by default, host-machine uid+gid are used
        - `out` (`str`; default `nbs`): directory to write executed notebooks to
        - `dst` (`str`: default `/src`): path inside container to mount current directory to  
        
        ### `Dockerfile`
        When building the Docker image (in any of the above modes), if a `Dockerfile` is present in the repository, it will be built and used as the base image (and any `gsmo.yml` configs applied on top of it).
        
        [`gsmo.yml`]: #gsmo-yml
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >3.8
Description-Content-Type: text/markdown
