Commit c0314204 authored by Lars van den Haak's avatar Lars van den Haak
Browse files

updated to iPython extension

parent 9a9ef85a
......@@ -2,3 +2,8 @@ __pycache__/
*.py[cod]
*$py.class
.mypy_cache/
.ipynb_checkpoints/
build/
env/
nb_mypy.egg-info/
\ No newline at end of file
Copyright (c) 2021 Lars van den Haak, Tom Verhoeff
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.
\ No newline at end of file
%% Cell type:markdown id: tags:
# Nb-Mypy
# Nb Mypy
## Mypy Type Checking in Jupyter Notebooks
© 2020 - Lars van den Haak, Tom Verhoeff (Eindhoven University of Technology)
© 2021 - Lars van den Haak, Tom Verhoeff (Eindhoven University of Technology)
---
_Nb-Mypy_ is a facility to do automatic [`mypy`](http://mypy-lang.org/) type checking of Python code
in Jupyter notebooks.
_Nb Mypy_ is a facility to automatically run [`mypy`](http://mypy-lang.org/) on Jupyter notebook cells as they are executed, whilst retaining information about the execution history.
%% Cell type:markdown id: tags:
## Table of Contents
......@@ -20,75 +20,45 @@
%% Cell type:markdown id: tags:
## Installation
* Download `nb-mypy.py` from https://gitlab.tue.nl/jupyter-projects/nb-mypy.
* Move it to your IPython profile's startup directory.
* Locate the IPython directory by
```shell
$ ipython locate
```
* In this directory, the default profile's startup directory is `default_profile/startup/`.
* On Linux, typically, the installed script will have the path
`/YourHomeDirectoryPath/.ipython/default_profile/startup/nb-mypy.py`.
* Install `mypy` and `astor`:
```shell
$ pip3 install mypy astor
```
Whenever IPython starts (e.g. as a kernel in a Jupyter notebook),
this script will be run, and it defines the _line magic command_ `%nb_mypy`.
* _Nb Mypy_ relies on the packages mypy and astor, which you can install via `python3 -m pip install mypy astor`.
* _Nb Mypy_ can be installed with `python3 -m pip install nb_mypy`.
%% Cell type:markdown id: tags:
## Usage
Here are the ways to use the line magic `%nb_mypy`:
* `%nb_mypy -v`: show version
* `%nb_mypy`: show the current state
* `%nb_mypy On`: enable automatic type checking
* `%nb_mypy Off`: disable automatic type checking
* `%nb_mypy DebugOn`: enable debug mode
* `%nb_mypy DebugOff`: disable debug mode
%% Cell type:markdown id: tags:
An unknown argument will result in an error message and a list of known commands:
If you want to apply automatic type checking, you can load the extension as:
%% Cell type:code id: tags:
``` python
%nb_mypy unknown
%load_ext nb_mypy
```
%% Cell type:markdown id: tags:
A robust way of attempting to enable type checking is shown in the next code cell.
%% Cell type:code id: tags:
``` python
# enable mypy type checking, if installed
if 'nb_mypy' in get_ipython().magics_manager.magics.get('line'):
%nb_mypy On
```
With the line magic `%nb_mypy` you can modify the behaviour of _Nb Mypy_
* `%nb_mypy -v`: show version
* `%nb_mypy`: show the current state
* `%nb_mypy On`: enable automatic type checking
* `%nb_mypy Off`: disable automatic type checking
* `%nb_mypy DebugOn`: enable debug mode
* `%nb_mypy DebugOff`: disable debug mode
%% Cell type:markdown id: tags:
A more verbose way of doing this:
An unknown argument will result in an error message and a list of known commands:
%% Cell type:code id: tags:
``` python
# enable mypy type checking, if installed (verbose)
if 'nb_mypy' in get_ipython().magics_manager.magics.get('line'):
%nb_mypy -v
%nb_mypy On
%nb_mypy
else:
print("nb-mypy.py not installed")
%nb_mypy unknown
```
%% Cell type:markdown id: tags:
## Type Hint Checking Examples
......@@ -161,11 +131,11 @@
'42'
%% Cell type:code id: tags:
``` python
answer: int = 42 # can give new type
answer: str = '42' # can give new type
```
%% Cell type:code id: tags:
``` python
......@@ -359,11 +329,11 @@
%%%% Output: error
---------------------------------------------------------------------------
NameError Traceback (most recent call last)
<ipython-input-20-2c235a16a669> in <module>
<ipython-input-19-2c235a16a669> in <module>
1 # reveal_type is not defined, but interpreted by mypy
----> 2 reveal_type(mid([1, 2]))
3 reveal_type(mid(['a', 'b']))
NameError: name 'reveal_type' is not defined
......
# Nb-Mypy
# Nb Mypy
`Nb-Mypy` is a facility to automatically run `mypy` on Jupyter notebook cells as they are executed.
_Nb Mypy_ is a facility to automatically run `mypy` on Jupyter notebook cells as they are executed, whilst retaining information about the execution history.
## Installation
* Download the [`nb-mypy.py`](nb-mypy.py) script and move it into your IPython profile's startup directory.
* _Nb Mypy_ relies on the packages mypy and astor, which you can install via `python3 -m pip install mypy astor`.
* _Nb Mypy_ can be installed with `python3 -m pip install nb_mypy`.
The IPython directory can be found by running `ipython locate` in a terminal.
Within this directory, the default profile's startup directory is `profile_default/startup/`.
For example, on Linux the script could exist on a path like this:
```shell script
/yourhomedir/.ipython/profile_default/startup/nb-mypy.py
```
* This script relies on `mypy` and `astor`.
So, make sure to have them installed. E.g.
```shell script
$ pip3 install mypy astor
```
Once installed, the `%nb_mypy` line magic becomes available in Jupyter notebooks using the IPython kernel.
You will need to restart your kernel after installing or updating `nb-mypy.py`.
At startup, automatic type checking is _disabled_.
> If you want it to be _enabled_ at startup, then make the following change in `nb-mypy.py`.
> Change `__Nb_Mypy_TypeChecker = __MypyIPython(False)` into
> `__Nb_Mypy_TypeChecker = __MypyIPython(True)`.
Once installed, you can load it via `%load_ext nb_mypy` in a cell of a Jupyter notebook using the IPython kernel.
## Usage
In Jupyter notebooks where you want to apply
automatic type checking,
you can enable type checking by executing
(in a code cell) the line magic `%nb_mypy On`.
you can load this extension to do type checking by executing
(in a code cell) the line magic `%load_ext nb_mypy`.
A robust way of attempting to enable type checking is
```python
if 'nb_mypy' in get_ipython().magics_manager.magics.get('line'):
%nb_mypy On
With the line magic `%nb_mypy` you can modify the behaviour of _Nb Mypy_
```
Here are the ways to use the line magic `%nb_mypy`
* `%nb_mypy -v`: show version
......@@ -52,4 +30,4 @@ Here are the ways to use the line magic `%nb_mypy`
## Examples
For examples, see the Jupyter notebook [`Nb-Mypy.ipynb`](Nb-Mypy.ipynb).
For examples, see the Jupyter notebook [`Nb_Mypy.ipynb`](Nb_Mypy.ipynb).
This diff is collapsed.
[build-system]
requires = [
"setuptools>=42",
"wheel",
"astor",
"mypy"
]
build-backend = "setuptools.build_meta"
\ No newline at end of file
[metadata]
name = nb_mypy
version = 1.0.0
author = Lars van den Haak, Tom Verhoeff
author_email = l.b.vandenhaak@gmail.com
description = Nb Mypy is a facility to automatically run mypy on Jupyter notebook cells as they are executed, whilst retaining information about the execution history.
long_description = file: README.md
long_description_content_type = text/markdown
url = https://gitlab.tue.nl/jupyter-projects/nb_mypy
project_urls =
Bug Tracker = https://gitlab.tue.nl/jupyter-projects/nb_mypy/-/issues
classifiers =
Programming Language :: Python :: 3
License :: OSI Approved :: MIT License
Operating System :: OS Independent
Framework :: IPython
[options]
packages = find:
python_requires = >=3.6
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment