Metadata-Version: 2.1
Name: nbless
Version: 0.2.35
Summary: Construct, deconstruct, convert, and run Jupyter notebooks.
Home-page: https://github.com/marskar/nbless
Author: Martin Skarzynski
Author-email: marskar@gmail.com
License: UNKNOWN
Description: Nbless: a Python package for programmatic Jupyter notebook workflows
        ====================================================================
        
        |Build| |Chat| |Coverage| |License| |PyPI| |Python versions| |PyUp| |Repo status|
        
        Introduction
        ------------
        
        The ``nbless`` Python package allows you to (de)construct, convert, and execute `Jupyter
        Notebooks <http://jupyter-notebook.readthedocs.io/en/latest/examples/Notebook/What%20is%20the%20Jupyter%20Notebook.html>`__
        in
        
        - your terminal (e.g. ``bash``, ``zsh``, ``fish``, etc.) or
        - your favorite Python environment (e.g. `PyCharm <https://www.jetbrains.com/pycharm/>`__ or `Visual Studio Code <https://code.visualstudio.com/docs/python/python-tutorial>`__).
        
        The ``nbless`` Python package consists of 6 Python functions and shell commands:
        
        - nbconv_, which converts a notebook into various formats.
        - nbdeck_, which prepares a notebook to be viewed as or converted into slides.
        - nbexec_, which runs a notebook from top to bottom and saves an executed version.
        - nbless_, which calls ``nbuild`` and ``nbexec`` to create and execute a notebook.
        - nbraze_, which extracts code and markdown files from a notebook.
        - nbuild_, which creates a notebook from source files, e.g. Python (`.py`) and R (`.R`) scripts, markdown (``.md``), and text (``.txt``) files.
        
        For a related package that provides programmatic tools for working with `R Markdown <https://rmarkdown.rstudio.com/authoring_quick_tour.html>`__ (Rmd) files,
        check out the `Rmdawn Python package <https://py4ds.github.io/rmdawn/>`__.
        
        Documentation and code
        ----------------------
        
        The documentation is hosted at https://py4ds.github.io/nbless/.
        
        The code is hosted at https://github.com/py4ds/nbless.
        
        Installation
        ------------
        
        .. code:: sh
        
            pip install nbless
        
        or clone the `repo <https://github.com/py4ds/nbless>`__, e.g.
        ``git clone https://github.com/py4ds/nbless`` and install locally
        using setup.py (``python setup.py install``) or ``pip``
        (``pip install .``).
        
        Usage
        -----
        
        .. _nbconv:
        
        Converting Jupyter notebooks with ``nbconv``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        The ``nbconv`` shell command can export a
        notebook to many different formats using the ``nbconvert`` library.
        Converting to all formats except HTML requires pandoc.
        Exporting to PDF requires LaTeX.
        
        The supported exporters are
        
            - asciidoc
            - pdf
            - html
            - latex
            - markdown
            - python
            - rst
            - script
            - slides
        
        For example, ``nbconv`` can create a python script by extracting
        the content from code cells and discarding all output and markdown
        content.
        
        .. code:: sh
        
            nbconv notebook.ipynb --exporter python
            # Or
            nbconv notebook.ipynb -e python
        
        
        In the example above, the output file would be ``notebook.py``, but you can
        provide a more descriptive name for the output file with the ``--out_file`` or
        ``-o`` flag:
        
        .. code:: sh
        
            nbconv notebook.ipynb --out_file script.py
            # Or
            nbconv notebook.ipynb -o script.py
        
        If the ``exporter`` is not provided, ``nbconv`` will try to infer the exporter type
        from the ``out_file`` extension.
        
        If neither the ``exporter`` or ``out_file`` arguments are provided, the exporter will be set to html.
        
        .. code:: sh
        
            nbconv notebook.ipynb
        
        Unlike the shell command,
        the ``nbconv`` Python function does not create a file on its own.
        To create a converted file with Python, use the ``pathlib`` library.
        
        .. code:: python
        
            from pathlib import Path
            from nbless import nbconv
        
            # Create notebook.py from notebook.ipynb
            filename, contents = nbconv("notebook.ipynb", "python")
            Path(filename).write_text(contents)
        
            # Create report.html from notebook.ipynb
            filename, contents = nbconv("notebook.ipynb", "html")
            Path('report.html').write_text(contents)
        
        .. _nbdeck:
        
        Creating HTML slides with ``nbdeck`` and ``nbconv``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        With ``nbdeck``, you can prepare HTML slides from a Jupyter notebook.
        
        .. code:: sh
        
            nbdeck notebook.ipynb -o slides.ipynb
            nbconv slides.ipynb  -e slides -o slides.html
        
        You can run ``nbdeck`` without ``nbconv``,
        if you do not want to create HTML slides and instead want to use
        `nbviewer <https://nbviewer.jupyter.org/>`__ or the
        `RISE extension <https://github.com/damianavila/RISE#rise>`__.
        If an ``out_file`` name is not provided, the notebook file contents will be
        printed.
        You can provide a more descriptive name for the executed output notebook with
        the ``--out_file`` or ``-o`` flag or by redirecting the output to a file with
        ``>``.
        
        .. code:: sh
        
            nbdeck notebook.ipynb --out_file slides.ipynb
            # Or
            nbdeck notebook.ipynb -o slides.ipynb
            # Or
            nbdeck notebook.ipynb > slides.ipynb
        
        Unlike the shell command,
        the ``nbdeck`` Python function does not create a file on its own.
        To create a converted file, use the ``nbformat`` and  ``pathlib`` libraries.
        
        .. code:: python
        
            import nbformat
            from nbless import nbconv, nbdeck
        
            # Create HTML slides from notebook.ipynb in notebooks folder
            nbformat.write(nbdeck("notebook.ipynb"), "slides.ipynb")
            filename, contents = nbconv("slides.ipynb", "slides")
            Path(filename).write_text(contents)
        
        .. _nbexec:
        
        Executing a notebook with ``nbexec``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        The ``nbexec`` command runs the input notebook from top to bottom.
        If an ``out_file`` name is not provided, the executed notebook contents will be
        printed.
        
        .. code:: sh
        
            nbexec notebook.ipynb
        
        You can provide a more descriptive name for the executed output notebook with
        the ``--out_file`` or ``-o`` flag or by redirecting the output to a file with
        ``>``.
        
        .. code:: sh
        
            nbexec notebook.ipynb --out_file executed.ipynb
            # Or
            nbexec notebook.ipynb -o executed.ipynb
            # Or
            nbexec notebook.ipynb > executed.ipynb
        
        The default kernel is ``python3``, but it is possible to specify the kernel
        that will be used to run notebook with the ``--kernel`` or ``-k`` flag.
        
        .. code:: sh
        
            nbexec notebook.ipynb --kernel ir --out_file notebook.ipynb
            # Or
            nbexec notebook.ipynb -k ir -o notebook.ipynb
        
        You can preview the default output filename and the raw notebook output by
        running ``nbexec`` with only the positional argument:
        
        .. code:: sh
        
            nbexec notebook.ipynb
        
        Unlike the shell command,
        the ``nbexec`` Python function does not create a file on its own.
        To create a notebook file, use the ``nbformat`` library.
        
        .. code:: python
        
            import nbformat
            from nbless import nbexec
        
            # Create notebook.ipynb from notebook.ipynb
        	nb = nbexec("notebook.ipynb")
            nbformat.write(nb, "executed.ipynb")
        	Rnb = nbexec("Rnotebook.ipynb")
            nbformat.write(Rnb, "Rexecuted.ipynb", kernel="ir")
        
        .. _nbless:
        
        Creating and executing a Jupyter notebook with ``nbless``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        The ``nbless`` shell command executes a notebook created from code and markdown/text files.
        
        .. code:: sh
        
            nbless README.md plot.py notes.txt > executed.ipynb
        
        The default kernel is ``python3``, but it is possible to specify the kernel that will be used to run notebook with the
        ``--kernel`` or ``-k`` flag.
        
        .. code:: sh
        
            nbless README.md plot.py notes.txt --kernel ir > Rnotebook.ipynb
            # Or
            nbless README.md plot.py notes.txt -k ir > Rnotebook.ipynb
        
        Instead of redirecting to a file (``>``), you can use the ``--out_file``
        or ``-o`` flag:
        
        .. code:: sh
        
            nbless README.md plot.py notes.txt --out_file executed.ipynb
            # Or
            nbless README.md plot.py notes.txt -o executed.ipynb
        
        Unlike the shell command,
        the ``nbless`` Python function does not create a file on its own.
        To create a notebook file, use the ``nbformat`` library.
        
        .. code:: python
        
            import nbformat
            from nbless import nbless
        
            # Build and execute a notebook with nbless
        	nb = nbless(["plot.py", "notes.txt"])
            nbformat.write(nb, "executed.ipynb")
        	Rnb = nbless(["plot.R", "notes.txt"], kernel="ir")
            nbformat.write(Rnb, "Rexecuted.ipynb")
        
        .. _nbraze:
        
        Extracting source files from a Jupyter notebook with ``nbraze``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        The ``nbraze`` shell command takes the contents of `Jupyter Notebook code cells
        <https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Running%20Code.html>`__
        and turns them into code files, e.g. Python or R code files (``.py`` or
        ``.R``). The contents of `markdown cells
        <https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html>`__
        are turned into markdown files.
        
        .. code:: sh
        
            nbraze notebook.ipynb
        
        The default code file extension for ``nbraze`` is ``py``, but it is possible to
        set the file extension with the ``--extension`` or ``-e`` flag. If the
        ``language_info`` key is defined in the Jupyter notebook metadata, ``nbraze``
        can try to infer the code file extension from the programming language.
        
        .. code:: sh
        
            nbraze notebook.ipynb --extension R
            nbraze notebook.ipynb -e js
        
        .. code:: python
        
            from nbless import nbraze
        
            # Create source files from notebook.ipynb
        	nbraze("notebook.ipynb")
        	nbraze("notebook.ipynb", extension="R")
        
        .. _nbuild:
        
        Creating a Jupyter notebook with ``nbuild``
        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
        
        The ``nbuild`` shell command takes the contents of Python or R code files
        (``.py`` or ``.R``) and stores them as `Jupyter Notebook code
        cells <https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Running%20Code.html>`__.
        The contents of all other files are stored in `markdown
        cells <https://jupyter-notebook.readthedocs.io/en/stable/examples/Notebook/Working%20With%20Markdown%20Cells.html>`__.
        
        .. code:: sh
        
            nbuild README.md plot.py notes.txt > notebooks/notebook.ipynb
        
        Instead of redirecting to a file (``>``), you can use the ``--out_file``
        or ``-o`` flag:
        
        .. code:: sh
        
            nbuild README.md plot.py notes.txt --out_file notebooks/notebook.ipynb
            # Or
            nbuild README.md plot.py notes.txt -o notebooks/notebook.ipynb
        
        You can preview the raw notebook output by running ``nbuild`` with only the positional arguments:
        
        .. code:: sh
        
            nbuild README.md plot.py notes.txt
        
        The ``nbuild`` Python function does not create a file on its own.
        To create a notebook file, use the ``nbformat`` library.
        
        .. code:: python
        
            import nbformat
            from nbless import nbuild
        
            # Create notebook.ipynb from plot.py and notes.txt
            nb = nbuild(["plot.py", "notes.txt"])
            nbformat.write(nb, "notebook.ipynb")
        
        Related projects
        ----------------
        
        - `pandoc <https://pandoc.org/MANUAL.html#creating-jupyter-notebooks-with-pandoc>`__
        - `jupytext <https://github.com/mwouts/jupytext>`__
        - `notedown <https://github.com/aaren/notedown>`__
        
        Next Steps
        ----------
        
        Currently, notebook metadata is lost when using ``nbraze``/``nbuild``/``nbless``.
        
        - Enable ``nbuild``/``nbless`` to accept metadata via a ``metadata.json`` file.
        - Enable ``nbraze`` to output metadata via a ``metadata.json`` file.
        
        .. |Build| image:: https://travis-ci.org/py4ds/nbless.svg?branch=master
           :target: https://travis-ci.org/py4ds/nbless
        .. |Chat| image:: https://badges.gitter.im/py4ds/nbless.svg
           :alt: Join the chat at https://gitter.im/py4ds/nbless
           :target: https://gitter.im/py4ds/nbless?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
        .. |Coverage| image:: https://img.shields.io/codecov/c/gh/py4ds/nbless.svg
           :target: https://codecov.io/gh/py4ds/nbless
        .. |License| image:: https://img.shields.io/badge/License-MIT-purple.svg
           :target: https://opensource.org/licenses/MIT
        .. |PyPI| image:: https://img.shields.io/pypi/v/nbless.svg
           :target: https://pypi.python.org/pypi/nbless
        .. |Repo status| image:: https://www.repostatus.org/badges/latest/active.svg
           :alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed.
           :target: https://www.repostatus.org/#active
        .. |PyUp| image:: https://pyup.io/repos/github/py4ds/nbless/shield.svg
           :target: https://pyup.io/repos/github/py4ds/nbless/
        .. |Python versions| image:: https://img.shields.io/pypi/pyversions/nbless.svg
           :alt: PyPI - Python Version
           :target: https://www.python.org/downloads/
        
Platform: UNKNOWN
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.6
Description-Content-Type: text/x-rst
