README.md.j2

<table>
  <tr>
    <td colspan=2>
      <strong>{{project.name}}</strong>&nbsp;&nbsp;&nbsp;&nbsp;
      <a href={{pypi.project_url}}><img src="https://img.shields.io/pypi/l/{{project.name}}.svg"></a>
      <a href={{pypi.project_url}}><img src="https://badge.fury.io/py/{{project.name}}.svg"></a>
      {%for action in github.actions%}<a href="{{action.url}}"><img src="{{action.url}}/badge.svg"></a>{%endfor%}
    </td>
  </tr>
  <tr>
    <td width=15%><img src={{github.raw_url}}/master/img/icon.png style="width:150px"></td>
    <td>
    Import utilities for python
    </td>
  </tr>
</table>

---------------------------------------------------------------------------------

{{markdown_toc(__template__, level=2)}}

---------------------------------------------------------------------------------

## Overview

Import utilities for python 

---------------------------------------------------------------------------------

## Installation

See [pypi](https://pypi.org/project/shimport/) for available releases.

```bash
pip install shimport
```

---------------------------------------------------------------------------------

## Usage

### Simple lazy modules

```pycon
>>> import shimport 
>>> pathlib = shimport.lazy('pathlib')
>>> print(pathlib.Path('.').absolute)
<bound method Path.absolute of PosixPath('.')>
>>>
```

---------------------------------------------------------------------------------

### Filtering module contents

#### Filtering for Public Functions

Suppose you want to retrieve just the function-definitions from a module namespace.  

Using `shimport.wrapper` let's you slice and dice:

```pycon
>>> import shimport
>>> wrapper = shimport.wrapper("os.path")
>>> wrapper = wrapper.prune(only_functions=True)
>>> print(wrapper.namespace.keys())
dict_keys(['abspath', 'basename', 'commonpath', 'commonprefix', 'dirname', 'exists', 'expanduser', 'expandvars', 'getatime', 'getctime', 'getmtime', 'getsize', 'isabs', 'isdir', 'isfile', 'islink', 'ismount', 'join', 'lexists', 'normcase', 'normpath', 'realpath', 'relpath', 'samefile', 'sameopenfile', 'samestat', 'split', 'splitdrive', 'splitext'])
>>>
```

#### Filtering using Chaining / Fluid Style

Some use-cases for `shimport` involve scenarios that aren't great with declarative-style development.  

So, there's good support for [chaining (aka fluent)](https://en.wikipedia.org/wiki/Fluent_interface) programming style as you can see below.  (Note that indention here follows fluent-style that shed/black should support)

```pycon
>>> import shimport 
>>> (
...   shimport
...   .wrapper('os.path')
...   .prune(only_data=True)
...   .prune(val_predicate=lambda v: v=='/')
...   .namespace.keys()
... )
dict_keys(['sep'])
>>>
```

```pycon
>>> import typing, shimport
>>> (
...   shimport
...   .wrapper("os.path")
...   .prune(
...       exclude_private=True,
...       filter_module_origin=True)
... )
<ModulesWrapper[os.path]>
>>>
```

#### Filtering for Classes

Grab only the classes from the given namespace:

```pycon
>>> import shimport 
>>> namespace=shimport.wrapper('pathlib').filter(only_classes=True)
>>> assert 'Path' in namespace

# Grab only subclasses of a given class from the given namespace
#>>> plugins = shimport.wrapper('my_app.plugins').prune(...)
#>>>
```

#### Filtering for Data

Grab only the classes from the given namespace:

```pycon
>>> import shimport 
>>> namespace = shimport.wrapper('os.path').filter(only_data=True)
>>> assert 'sep' in namespace
>>>
```

---------------------------------------------------------------------------------