Skip to content

Commit a9b47a6

Browse files
martinRenoumartinRenou
authored
Merge pull request #10 from mwcraig/add-license-install
Add a license, update README with local install instructions
2 parents 60fed8c + 1cfd178 commit a9b47a6

File tree

4 files changed

+310
-4
lines changed

4 files changed

+310
-4
lines changed

‎LICENSE.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
BSD 3-Clause License
2+
3+
Copyright (c) 2020, M. Bektas, M. Craig, I. Dafna, M. Renou
4+
All rights reserved.
5+
6+
Redistribution and use in source and binary forms, with or without
7+
modification, are permitted provided that the following conditions are met:
8+
9+
* Redistributions of source code must retain the above copyright notice, this
10+
list of conditions and the following disclaimer.
11+
12+
* Redistributions in binary form must reproduce the above copyright notice,
13+
this list of conditions and the following disclaimer in the documentation
14+
and/or other materials provided with the distribution.
15+
16+
* Neither the name of the copyright holder nor the names of its
17+
contributors may be used to endorse or promote products derived from
18+
this software without specific prior written permission.
19+
20+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

‎README.md

Lines changed: 84 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,87 @@
1-
# Tools for managing a collection of notebooks
1+
# The Jupyter Widget Ecosystem
22

3-
## Credit and license
3+
## Tutorial, JupyterCon 2020
44

5-
Some of these tools (and all of the idea for them) is from [Jake VanerPlas](https://jakevdp.github.io/)'s [Python Data Science Handbook](https://github.com/jakevdp/PythonDataScienceHandbook).
5+
## Installation on your own computer
66

7-
The files `add_navigation.py` and `generate_contents.py` are modified from the same files in the Handbook, whose code license, a copy of which is in [licenses/LICENSE-CODE](licenses/LICENSE-CODE).
7+
*You do not have to install the software on your computer to do the tutorial. JupyterCon will provide an environment for going through the materials. Follow these instruction if you want to run it on your computer.*
8+
9+
The code in the tutorial has been written using Python 3; many of the dependencies may not be available for Python 2.7.
10+
11+
We **strongly recommend** using the Anaconda Python distribution. You can install either the full [anaconda distribution](https://www.continuum.io/downloads) (very extensive, but large) or [miniconda](https://conda.io/miniconda.html) (much smaller, only essential packages).
12+
13+
Almost all of the examples will work in either the regular Jupyter notebook or in JupyterLab. The instructions below assume you will be using JupyterLab.
14+
15+
There are also download instructions below for installation using pip, which should work with any Python distribution.
16+
17+
## Download this repository
18+
19+
You can do this with either
20+
`git clone https://github.com/jupytercon/2020-widgets-tutorial` at the command
21+
line or by downloading this repostiory as a [Zip file](https://github.com/jupytercon/2020-widgets-tutorial/archive/master.zip).
22+
23+
## conda installation instructions
24+
25+
The steps below will get you a working environment.
26+
27+
```bash
28+
conda env create -f environment.yml
29+
30+
conda activate widgets-jcon20
31+
32+
# Create a kernel for this environment
33+
ipython kernel install --name widgets-jcon20 --display-name widgets-jcon20 --sys-prefix
34+
```
35+
36+
### Windows users
37+
The installation instructions were tested on an up-to-date version of Windows 10 Professional. If you encounter any issues on Windows please open an issue or contact us through slack.
38+
39+
## pip installation instructions
40+
41+
If you are not using the anaconda python distribution, please use the instructions below.
42+
43+
```bash
44+
pip install -r requirements.txt
45+
46+
# Create a kernel for this environment
47+
ipython kernel install --name widgets-jcon20 --display-name widgets-jcon20 --sys-prefix
48+
```
49+
50+
## Install JupyterLab extensions
51+
52+
In order to install the JupyterLab extensions, you need `nodejs` to be installed. If you use `conda` it should have been already installed for you when you created your environment.
53+
54+
55+
If you do not use `conda`, see [https://nodejs.org/en/download/](https://nodejs.org/en/download/) or [https://nodejs.org/en/download/package-manager/](https://nodejs.org/en/download/package-manager/) for download and installation instructions.
56+
57+
58+
Now you can install the JupyterLab extensions:
59+
60+
```bash
61+
# This may take several minutes
62+
jupyter labextension install @jupyter-widgets/jupyterlab-manager @jupyter-widgets/jupyterlab-sidecar bqplot
63+
```
64+
65+
<!-- **Only if we use them: `ipysheet ipytree`** -->
66+
67+
## Check your installation
68+
69+
To check your installation, please download the script [install_check.py](https://raw.githubusercontent.com/jupytercon/2020-widgets-tutorial/master/install_check.py) and run it:
70+
71+
```bash
72+
python install_check.py
73+
```
74+
75+
## Tutorial materials
76+
77+
To get the tutorial materials, clone this repository. *We anticipate making changes to the tutorial content through the end of October 2, 2020.*
78+
79+
To update your copy of the tutorial materials, navigate in a terminal to folder these materials are in then run `git pull`. An alternative is to download the repository again as a zip file.
80+
81+
## Any ipywidgets or custom widgets library question?
82+
83+
Please join us on the Gitter channel: https://gitter.im/jupyter-widgets/Lobby
84+
85+
## Running into trouble?
86+
87+
Please let us know! You can open an issue on this repository by clicking "Issues" under the repo name on GitHub, then the "New Issue" button in the upper right.

‎environment.yml

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
name: widgets-jcon20
2+
channels:
3+
- conda-forge
4+
dependencies:
5+
- python=3.8
6+
- pip
7+
- notebook
8+
- numpy
9+
- scikit-image
10+
- scipy
11+
- pandas
12+
- requests
13+
- ipywidgets
14+
- bqplot
15+
- ipyleaflet=0.12.6
16+
- pythreejs
17+
- ipycanvas
18+
- ipyevents
19+
- ipysheet
20+
- ipytree
21+
- ipympl
22+
- pywwt
23+
- sidecar
24+
- voila=0.1
25+
- ipyvuetify
26+
- voila-vuetify
27+
- jupyterlab=2
28+
- ipyvolume=0.6.0a6
29+
- nodejs=13

‎install_check.py

Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
from subprocess import check_call, CalledProcessError
2+
3+
4+
FIX_PREFIX = '----->'
5+
6+
tutorial_name = 'Jupyter widget ecosystem'
7+
8+
requirements = [
9+
'notebook',
10+
'ipywidgets',
11+
'bqplot',
12+
'ipyleaflet',
13+
'ipyvolume',
14+
'pythreejs',
15+
'ipyevents',
16+
'ipysheet',
17+
'ipytree',
18+
'pywwt',
19+
'jupyterlab'
20+
]
21+
22+
import_result = {p: False for p in requirements}
23+
24+
print("Checking requirements for {}".format(tutorial_name), end='')
25+
26+
for package in requirements:
27+
try:
28+
__import__(package)
29+
import_result[package] = True
30+
except ImportError:
31+
pass
32+
print('.', end='', flush=True)
33+
34+
print()
35+
success = all(import_result.values())
36+
37+
# List compatible versions for each package
38+
version_check_packages = {'ipywidgets': ['7.5'],
39+
'notebook': ['6'],
40+
'jupyterlab': ['2'],
41+
'ipyvolume': ['0.6.0-alpha.6'],
42+
}
43+
44+
if success:
45+
print('\tAll required packages installed')
46+
else:
47+
print(FIX_PREFIX, 'Please install these missing packages '
48+
'for the tutorial "{}":'.format(tutorial_name))
49+
missing = [k for k, v in import_result.items() if not v]
50+
print('\t' + '\n\t'.join(missing))
51+
52+
print('Checking voila version:')
53+
54+
try:
55+
check_call(['voila', '--version'])
56+
print('\tVoila is correctly installed')
57+
except CalledProcessError:
58+
print('\tVoila is not installed! Please install it by running one '
59+
'of the following:')
60+
print(' conda install -c conda-forge voila')
61+
print(' pip install voila')
62+
63+
print('Checking version numbers of these packages: ',
64+
', '.join(version_check_packages.keys()))
65+
66+
67+
def version_checker(package_name, version, nbextension=None):
68+
good_version = any(version.startswith(v) for
69+
v in version_check_packages[package_name])
70+
if nbextension is None:
71+
nbextension = package_name
72+
if not good_version:
73+
newest = version_check_packages[package_name][-1]
74+
print('\n**** Please upgrade {} to version {} by running:'.format(package_name,
75+
newest))
76+
print(' conda install {}={} # if you use conda'.format(package_name, newest))
77+
print(' pip install {}=={}'.format(package_name, newest))
78+
else:
79+
print('\t{} version is good!'.format(package_name))
80+
81+
82+
# Check as many packages as we can...
83+
84+
85+
try:
86+
import ipywidgets
87+
except ImportError:
88+
pass
89+
else:
90+
ipywidgets_version = ipywidgets.__version__
91+
version_checker('ipywidgets', ipywidgets_version)
92+
93+
try:
94+
import notebook
95+
except ImportError:
96+
pass
97+
else:
98+
notebook_version = notebook.__version__
99+
version_checker('notebook', notebook_version)
100+
101+
try:
102+
import jupyterlab
103+
except ImportError:
104+
pass
105+
else:
106+
jupyterlab_version = jupyterlab.__version__
107+
version_checker('jupyterlab', jupyterlab_version)
108+
109+
try:
110+
import ipyvolume
111+
except ImportError:
112+
pass
113+
else:
114+
ipyvolume_version = ipyvolume.__version__
115+
version_checker('ipyvolume', ipyvolume_version)
116+
117+
# Check that the appropriate kernel has been created
118+
119+
required_kernel = 'widgets-tutorial'
120+
121+
print('Checking whether kernel {} exists'.format(required_kernel))
122+
123+
import jupyter_client
124+
125+
known_kernels = list(jupyter_client.kernelspec.find_kernel_specs().keys())
126+
if required_kernel not in known_kernels:
127+
print(FIX_PREFIX, 'Please create custom kernel with: ',
128+
'ipython kernel install --name widgets-tutorial --display-name widgets-tutorial --sys-prefix')
129+
else:
130+
print('\tCustom kernel is correctly installed')
131+
132+
# Check that lab extensions are installed
133+
134+
print('Checking whether all Jupyter lab extensions are installed')
135+
136+
lab_extensions = [
137+
'@jupyter-widgets/jupyterlab-manager',
138+
'@jupyter-widgets/jupyterlab-sidecar',
139+
'bqplot',
140+
'jupyter-threejs',
141+
'jupyter-leaflet',
142+
'ipyvolume',
143+
'ipyevents',
144+
'ipysheet',
145+
'ipytree',
146+
'ipycanvas',
147+
'jupyter-matplotlib',
148+
'jupyter-vuetify',
149+
]
150+
151+
try:
152+
from jupyterlab.commands import check_extension
153+
except ImportError:
154+
print(FIX_PREFIX, 'Please install jupyterlab before checking extensions.')
155+
else:
156+
missing_extensions = []
157+
158+
for extension in lab_extensions:
159+
if not check_extension(extension):
160+
missing_extensions.append(extension)
161+
162+
if missing_extensions:
163+
print(FIX_PREFIX, 'These lab extensions are missing: ',
164+
', '.join(missing_extensions))
165+
print(FIX_PREFIX,' Run this to install them: jupyter labextension install ',
166+
' '.join(missing_extensions))
167+
else:
168+
print('\tAll extensions are installed!')

0 commit comments

Comments
 (0)