DOCSEARCHbyAlgolia
Submit Docs

pyforest

repository·master·Indexed 22 days ago

https://github.com/8080labs/pyforest

A tool for Data Scientists that automates Python imports in Jupyter Notebook and Jupyter Lab. It allows users to use popular libraries like pandas, numpy, and matplotlib immediately by detecting unused names and automatically injecting the corresponding import statements into the first cell of the notebook.

Tokens
2.6K
Snippets
14
Records
16
Agent score
76%

What's inside pyforest

  1. How pyforest automated imports work

    master

    pyforest allows you to use popular Data Science libraries without writing explicit import statements.

    How it works:

    1. You use a library name (e.g., pd.read_csv()).
    2. pyforest detects the unused name, imports the library for you, and automatically adds the corresponding import statement (e.g., import pandas as pd) to the first cell of your Jupyter notebook.
    3. If a library is never used, it is never imported, keeping your notebook clean and startup times fast.

    Key Behaviors:

    • Auto-completion: Works as expected. Triggering auto-completion will trigger the lazy import of the module.
    • Variable Safety: pyforest uses placeholders and will never mask or overwrite your local variables. If you manually define a variable with the same name as a pyforest placeholder, the placeholder simply becomes unavailable.
    • Reproducibility: The import statements are added to your notebook cells, ensuring the notebook remains sharable and reproducible.
    # Instead of writing:
# import pandas as pd
# df = pd.read_csv("data.csv")

# You can just write:
df = pd.read_csv("data.csv")

  2. Install JupyterLab extensions for pyforest

    master

    To install the necessary JupyterLab extensions for pyforest during development, you can use either the terminal or a Python script. Note that the installation process may take 30-60 seconds because it triggers a JupyterLab build.

    To see changes made to the JavaScript side, run JupyterLab in watch mode and refresh your browser (clearing the cache if necessary).

    # Via terminal
python -m pyforest install_labextension

# Via Python
import pyforest
pyforest.install_labextension()

  3. Deactivate or reactivate pyforest auto-import

    master

    If you want to manage how pyforest interacts with your IPython/Jupyter startup, use the following methods:

    To (temporarily) deactivate:

    Navigate to your IPython startup directory and adjust or delete the pyforest_autoimport.py file: ~/.ipython/profile_default/startup

    If you deactivate the auto-import, you must manually add import pyforest to the beginning of your notebooks to use its features.

    To (re)activate:

    Run the following command within a Jupyter cell, IPython, or a Python session:

    from pyforest.auto_import import setup
setup()

  4. Install Jupyter Notebook extensions for pyforest

    master

    To install the Jupyter Notebook extensions for pyforest, you can use the terminal or a Python script.

    Important: If you make changes to the JavaScript side of the extension, you must re-run the installation command to apply them.

    # Via terminal
python -m pyforest install_nbextension

# Via Python
import pyforest
pyforest.install_nbextension()

  5. Install pyforest and Jupyter extensions

    master

    To use pyforest's automated import functionality in Jupyter, install the package and its extensions via terminal or Anaconda prompt.

    Requirements:

    • Python 3.6 or above.
    • You must install your data science libraries (e.g., pandas, numpy) separately, as pyforest does not install dependencies for you.

    Note: After installation, restart your Jupyter server to ensure the JavaScript extension loads correctly. This process adds pyforest to your IPython default startup settings.

    pip install --upgrade pyforest
python -m pyforest install_extensions

  7. Install pyforest in editable mode for development

    master

    To install the local Python version of pyforest for development purposes, use pip with the editable flag. This allows changes to the source code to be reflected immediately without re-installation.

    pip install -e .

  8. Add custom import statements to pyforest

    master

    If you need specific imports that are not part of the default pyforest collection, you can define them in a user-specific file. These custom imports take precedence over pyforest's default imports.

    Create or edit the file at ~/.pyforest/user_imports.py and add your explicit import statements (e.g., import pandas as pd).

    Note: Only explicit imports (like import x as y) work; implicit imports (like from x import *) are not supported in the user imports file.

  9. How LazyImport works in pyforest

    master

    The LazyImport class is the core mechanism used by pyforest to enable automated, deferred imports. Instead of importing a package immediately, pyforest creates a LazyImport object that acts as a placeholder.

    Key Behaviors:

    • Triggered Imports: The actual import is only executed when the object is accessed via __dir__ (e.g., during autocomplete), __getattr__ (accessing an attribute), or __call__ (instantiating the object).
    • Collision Avoidance: LazyImport uses double-underscore (dunder) attributes (e.g., __import_statement__) rather than single underscores to minimize the risk of masking attributes of the libraries being imported.
    • Metadata Support: Once imported, LazyImport attempts to attach the original object's __doc__ and signature to itself to maintain a good developer experience in Jupyter/IPython.
    • Non-intrusive Representation: Calling repr() on a LazyImport object will not trigger an import, preventing accidental side effects when inspecting local variables (like calling locals()).
    # Conceptual usage of how pyforest handles an import internally:
# UnitRegistry = LazyImport("from pint import UnitRegistry")
# The import only happens when you actually use UnitRegistry
# e.g., UnitRegistry.some_attribute or UnitRegistry()

  10. Quickstart with pyforest automated imports

    master

    To use pyforest, simply import it at the beginning of your notebook or script. Once imported, pyforest automatically imports common data science libraries (like pandas, numpy, matplotlib, and seaborn) into your namespace. This allows you to use functions from these libraries without explicit import statements.

    import pyforest

# After importing pyforest, you can use libraries like pandas, numpy, and seaborn directly
import pandas as pd
import numpy as np
import seaborn as sns

df = pd.DataFrame(dict(a=np.arange(10)))
sns.distplot(df.a)

  11. Install pyforest extensions for Jupyter Notebook and JupyterLab

    master

    If you are using Jupyter Notebook or JupyterLab, you can install the necessary pyforest extensions by calling install_extensions(). This function automates the installation of the nbextension for Jupyter Notebook and the labextension for JupyterLab.

    Note: After the installation process completes, you must reload your Jupyter Notebook or JupyterLab browser windows for the changes to take effect.

    from pyforest.utils import install_extensions

install_extensions()

  12. How to deactivate pyforest auto-import

    master

    If you want to stop pyforest from automatically importing in your Jupyter or IPython sessions, you have two options depending on whether you want a permanent or temporary change:

    1. Temporary Deactivation: Open the pyforest_autoimport.py file located in your IPython startup folder and uncomment the import pyforest line. This allows you to manually control when the library is loaded.
    2. Permanent Deactivation: Delete the pyforest_autoimport.py file from your IPython startup folder entirely.
    # Inside ~/.ipython/profile_default/startup/pyforest_autoimport.py

try:
    import pyforest  # uncomment this line if you temporarily dont want to auto-import pyforest
    pass
except:
    pass