pax_global_header 0000666 0000000 0000000 00000000064 14636363363 0014527 g ustar 00root root 0000000 0000000 52 comment=14771aba95594ec3e2c7a27f214a2e91fd2dff6c
param-2.1.1/ 0000775 0000000 0000000 00000000000 14636363363 0012630 5 ustar 00root root 0000000 0000000 param-2.1.1/.flake8 0000664 0000000 0000000 00000001037 14636363363 0014004 0 ustar 00root root 0000000 0000000 [flake8]
# TODO tests should not be excluded (one day...)
include = param numbergen
exclude =
.venv,
jupyter_execute,
.git,
__pycache__,
.eggs,
*.egg,
doc,
dist,
build,
_build,
tests,
.ipynb_checkpoints
ignore = E114,
E116,
E126,
E128,
E129,
E2,
E3,
E4,
E5,
E731,
E701,
E702,
E703,
E704,
E722,
E741,
E742,
E743,
W503,
W504,
param-2.1.1/.gitattributes 0000664 0000000 0000000 00000000032 14636363363 0015516 0 ustar 00root root 0000000 0000000 __init__.py export-subst
param-2.1.1/.github/ 0000775 0000000 0000000 00000000000 14636363363 0014170 5 ustar 00root root 0000000 0000000 param-2.1.1/.github/FUNDING.yml 0000664 0000000 0000000 00000000110 14636363363 0015775 0 ustar 00root root 0000000 0000000 # These are supported funding model platforms
open_collective: holoviz
param-2.1.1/.github/workflows/ 0000775 0000000 0000000 00000000000 14636363363 0016225 5 ustar 00root root 0000000 0000000 param-2.1.1/.github/workflows/build.yaml 0000664 0000000 0000000 00000005323 14636363363 0020213 0 ustar 00root root 0000000 0000000 name: packages
on:
push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+'
- 'v[0-9]+.[0-9]+.[0-9]+a[0-9]+'
- 'v[0-9]+.[0-9]+.[0-9]+b[0-9]+'
- 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
# Dry-run only
workflow_dispatch:
schedule:
- cron: '0 13 * * SUN'
jobs:
conda_build:
name: Build Conda Packages
runs-on: 'ubuntu-latest'
defaults:
run:
shell: bash -l {0}
env:
CHANS_DEV: "-c pyviz/label/dev"
PKG_TEST_PYTHON: "--test-python=py37"
PYTHON_VERSION: "3.9"
CHANS: "-c pyviz"
CONDA_UPLOAD_TOKEN: ${{ secrets.CONDA_UPLOAD_TOKEN }}
steps:
- uses: actions/checkout@v4
- name: Fetch unshallow
run: git fetch --prune --tags --unshallow -f
- uses: actions/setup-python@v5
with:
python-version: "3.9"
- uses: conda-incubator/setup-miniconda@v3
with:
miniconda-version: "latest"
- name: Set output
id: vars
run: echo "tag=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
- name: conda setup
run: |
conda update --name base conda
conda install anaconda-client conda-build
pip install hatch
- name: conda build
run: |
VERSION=`hatch version` conda build conda.recipe/
- name: conda dev upload
if: (github.event_name == 'push' && (contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
run: |
anaconda --token $CONDA_UPLOAD_TOKEN upload --user pyviz --label=dev $(VERSION=`hatch version` conda build --output conda.recipe)
- name: conda main upload
if: (github.event_name == 'push' && !(contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
run: |
anaconda --token $CONDA_UPLOAD_TOKEN upload --user pyviz --label=dev --label=main $(VERSION=`hatch version` conda build --output conda.recipe)
pip_build:
name: Build PyPI Packages
runs-on: 'ubuntu-latest'
defaults:
run:
shell: bash -l {0}
steps:
- uses: actions/checkout@v4
- name: Fetch unshallow
run: git fetch --prune --tags --unshallow -f
- uses: actions/setup-python@v5
with:
python-version: "3.9"
- name: env setup
run: |
python -m pip install --upgrade pip
python -m pip install build
- name: pip build
run: |
python -m build
- name: Publish package to PyPI
if: github.event_name == 'push'
uses: pypa/gh-action-pypi-publish@release/v1
with:
user: ${{ secrets.PPU }}
password: ${{ secrets.PPP }}
packages_dir: dist/
param-2.1.1/.github/workflows/docs.yaml 0000664 0000000 0000000 00000004246 14636363363 0020047 0 ustar 00root root 0000000 0000000 name: docs
on:
push:
tags:
- 'v[0-9]+.[0-9]+.[0-9]+'
- 'v[0-9]+.[0-9]+.[0-9]+a[0-9]+'
- 'v[0-9]+.[0-9]+.[0-9]+b[0-9]+'
- 'v[0-9]+.[0-9]+.[0-9]+rc[0-9]+'
workflow_dispatch:
inputs:
target:
description: 'Site to build and deploy'
type: choice
options:
- dev
- main
- dryrun
required: true
default: dryrun
schedule:
- cron: '0 13 * * SUN'
jobs:
build_docs:
name: Documentation
runs-on: 'ubuntu-latest'
timeout-minutes: 120
defaults:
run:
shell: bash -l {0}
steps:
- uses: actions/checkout@v4
- name: Fetch unshallow
run: git fetch --prune --tags --unshallow -f
- uses: actions/setup-python@v5
with:
python-version: '3.9'
- name: Set output
id: vars
run: echo "tag=${GITHUB_REF#refs/*/}" >> $GITHUB_OUTPUT
- name: graphviz
run: sudo apt install graphviz graphviz-dev
- name: env setup
run: |
python -m pip install --upgrade pip
python -m pip install hatch
- name: build docs
run: hatch -v run docs:build
- name: Deploy dev
uses: peaceiris/actions-gh-pages@v4
if: |
(github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'dev') ||
(github.event_name == 'push' && (contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
with:
personal_token: ${{ secrets.ACCESS_TOKEN }}
external_repository: holoviz-dev/param
publish_dir: ./builtdocs
force_orphan: true
- name: Deploy main
if: |
(github.event_name == 'workflow_dispatch' && github.event.inputs.target == 'main') ||
(github.event_name == 'push' && !(contains(steps.vars.outputs.tag, 'a') || contains(steps.vars.outputs.tag, 'b') || contains(steps.vars.outputs.tag, 'rc')))
uses: peaceiris/actions-gh-pages@v4
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./builtdocs
cname: param.holoviz.org
force_orphan: true
param-2.1.1/.github/workflows/downstream_tests.yaml 0000664 0000000 0000000 00000001227 14636363363 0022520 0 ustar 00root root 0000000 0000000 name: downstream_tests
on:
# Run this workflow after the build workflow has completed.
workflow_run:
workflows: [packages]
types: [completed]
# Or by triggering it manually via Github's UI
workflow_dispatch:
inputs:
manual:
description: don't change me!
type: boolean
required: true
default: true
jobs:
downstream_tests:
uses: holoviz-dev/holoviz_tasks/.github/workflows/run_downstream_tests.yaml@main
with:
downstream_repos_as_json: "{\"downstream_repo\":[\"panel\", \"lumen\", \"holoviews\", \"datashader\", \"colorcet\"]}"
secrets:
ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
param-2.1.1/.github/workflows/test.yaml 0000664 0000000 0000000 00000005306 14636363363 0020074 0 ustar 00root root 0000000 0000000 name: tests
on:
push:
branches:
- main
pull_request:
branches:
- '*'
workflow_dispatch:
schedule:
- cron: '0 13 * * SUN'
concurrency:
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
pre_commit:
name: Run pre-commit hooks
runs-on: 'ubuntu-latest'
steps:
- uses: actions/checkout@v4
with:
fetch-depth: "1"
- name: set PY
run: echo "PY=$(python -VV | sha256sum | cut -d' ' -f1)" >> $GITHUB_ENV
- uses: actions/cache@v4
with:
path: ~/.cache/pre-commit
key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}
- name: pre-commit
uses: pre-commit/action@v3.0.0
test_suite:
name: Test ${{ matrix.python-version }}, ${{ matrix.platform }}
needs: [pre_commit]
runs-on: ${{ matrix.platform }}
strategy:
fail-fast: false
matrix:
platform: ['ubuntu-latest', 'windows-latest', 'macos-latest']
python-version: ${{ ( github.event_name == 'schedule' || github.event_name == 'workflow_dispatch' || ( github.event_name == 'push' && github.ref_type == 'tag' ) ) && fromJSON('["3.8", "3.9", "3.10", "3.11", "3.12", "pypy3.9"]') || fromJSON('["3.8", "3.10", "3.12"]') }}
timeout-minutes: 30
steps:
- uses: actions/checkout@v4
with:
fetch-depth: "100"
- name: Fetch unshallow
run: git fetch --prune --tags --unshallow -f
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python-version }}
allow-prereleases: true
- name: env setup
run: |
python -m pip install --upgrade pip
python -m pip install hatch
- name: temp patch pip for blosc2
if: contains(matrix.platform, 'ubuntu') && matrix.python-version == '3.8'
run: echo "PIP_ONLY_BINARY=blosc2" >> $GITHUB_ENV
- name: run unit tests
run: hatch -v run +py=${{ matrix.python-version }} tests:with_coverage
- name: run examples tests
# A notebook fails on Windows (UNIX path used in an example)
# No need to run these tests for PyPy really
if: contains(matrix.platform, 'ubuntu') && !startsWith(matrix.python-version, 'py')
run: hatch -v run +py=${{ matrix.python-version }} tests_examples:examples
- name: Upload coverage reports to Codecov
if: github.event_name == 'push' || github.event_name == 'pull_request'
uses: codecov/codecov-action@v4
with:
fail_ci_if_error: false
verbose: false
env:
CODECOV_TOKEN: ${{ secrets.CODECOV_TOKEN }}
param-2.1.1/.gitignore 0000664 0000000 0000000 00000000601 14636363363 0014615 0 ustar 00root root 0000000 0000000 *.py[cod]
#*#
*~
*.egg
*.egg-info
*.swp
*.DS_Store
*.so
*.o
*.out
*.lock
.ipynb_checkpoints
.vscode
dist/
.venv/
# Docs
builtdocs/
jupyter_execute/
doc/Reference_Manual/
doc/user_guide/data.pickle
doc/user_guide/output.csv
doc/reference/generated
# Unit test / Coverage report
.coverage
coverage.xml
# Versionning
param/_version.py
# asv benchmark
benchmarks/.asv
benchmarks/param
param-2.1.1/.gitmodules 0000664 0000000 0000000 00000000000 14636363363 0014773 0 ustar 00root root 0000000 0000000 param-2.1.1/.pre-commit-config.yaml 0000664 0000000 0000000 00000001273 14636363363 0017114 0 ustar 00root root 0000000 0000000 # This is the configuration for pre-commit, a local framework for managing pre-commit hooks
# Check out the docs at: https://pre-commit.com/
default_stages: [commit]
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v4.3.0
hooks:
- id: check-builtin-literals
- id: check-case-conflict
- id: check-docstring-first
- id: check-toml
- id: detect-private-key
- id: end-of-file-fixer
exclude: (\.min\.js$|\.svg$)
- id: trailing-whitespace
- repo: https://github.com/PyCQA/flake8
rev: 6.0.0
hooks:
- id: flake8
- repo: https://github.com/hoxbro/clean_notebook
rev: v0.1.10
hooks:
- id: clean-notebook
param-2.1.1/CODE_OF_CONDUCT.md 0000664 0000000 0000000 00000000454 14636363363 0015432 0 ustar 00root root 0000000 0000000 # Code of Conduct
For the code of conduct, see [HoloViz/HoloViz - CODE_OF_CONDUCT.md](https://github.com/holoviz/holoviz/blob/param-gov/CODE_OF_CONDUCT.md).
The Param Project’s equivalently named documents take precedence over any external materials referenced within this linked document above.
param-2.1.1/LICENSE.txt 0000664 0000000 0000000 00000002742 14636363363 0014460 0 ustar 00root root 0000000 0000000 Copyright (c) 2005-2022, HoloViz team.
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the
distribution.
* Neither the name of the copyright holder nor the names of any
contributors may be used to endorse or promote products derived
from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
param-2.1.1/README.md 0000664 0000000 0000000 00000005300 14636363363 0014105 0 ustar 00root root 0000000 0000000
| | |
| --- | --- |
| Build Status | [](https://github.com/holoviz/param/actions/workflows/test.yaml)
| Coverage | [](https://codecov.io/gh/holoviz/param) ||
| Latest dev release | [](https://github.com/holoviz/param/tags) [](https://holoviz-dev.github.io/param/) |
| Latest release | [](https://github.com/holoviz/param/releases) [](https://pypi.python.org/pypi/param) [](https://anaconda.org/pyviz/param) [](https://anaconda.org/conda-forge/param) [](https://anaconda.org/anaconda/param) |
| Python | [](https://pypi.org/project/param/)
| Docs | [](https://github.com/holoviz/param/tree/gh-pages) [](https://param.holoviz.org) |
| Binder | [](https://mybinder.org/v2/gh/holoviz/param/main?labpath=doc) |
| Support | [](https://discourse.holoviz.org/) |
Param is a library providing Parameters: Python attributes extended to have features such as type and range checking, dynamically generated values, documentation strings, default values, etc., each of which is inherited from parent classes if not specified in a subclass.
Param contains only two required Python files, with no external dependencies, and is provided freely for both non-commercial and commercial use under a BSD license, so that it can easily be included as part of other projects.
Please see [param's website](https://param.holoviz.org) for official releases, installation instructions, documentation, and examples.
param-2.1.1/benchmarks/ 0000775 0000000 0000000 00000000000 14636363363 0014745 5 ustar 00root root 0000000 0000000 param-2.1.1/benchmarks/README.md 0000664 0000000 0000000 00000005674 14636363363 0016240 0 ustar 00root root 0000000 0000000 # Benchmarking
`Param` uses ASV (https://asv.readthedocs.io) for benchmarking.
## Preparation
Install `asv` into your environment with for example:
```
hatch shell
cd benchmarks
pip install asv
```
ASV then runs benchmarks in isolated virtual environments that it creates using `virtualenv`.
## Running benchmarks
To run all benchmarks against the default `main` branch:
```
cd benchmarks
asv run
```
The first time this is run it will create a machine file to store information about your machine. Then a virtual environment will be created and each benchmark will be run multiple times to obtain a statistically valid benchmark time.
To list the benchmark timings stored for the `main` branch use:
```
asv show main
```
ASV ships with its own simple webserver to interactively display the results in a webbrowser. To use this:
```
asv publish
asv preview
```
and then open a web browser at the URL specified.
If you want to quickly run all benchmarks once only to check for errors, etc, use:
```
asv dev
```
instead of `asv run`.
## Adding new benchmarks
Add new benchmarks to existing or new classes in the `benchmarks/benchmarks` directory. Any class member function with a name that starts with `time` will be identified as a timing benchmark when `asv` is run.
Data that is required to run benchmarks is usually created in the `setup()` member function. This ensures that the time taken to setup the data is not included in the benchmark time. The `setup()` function is called once for each invocation of each benchmark, the data are not cached.
At the top of each benchmark class there are lists of parameter names and values. Each benchmark is repeated for each unique combination of these parameters.
If you only want to run a subset of benchmarks, use syntax like:
```
asv run -b ShadeCategorical
```
where the text after the `-b` flag is used as a regex to match benchmark file, class and function names.
## Benchmarking code changes
You can compare the performance of code on different branches and in different commits. Usually if you want to determine how much faster a new algorithm is, the old code will be in the `main` branch and the new code will be in a new feature branch. Because ASV uses virtual environments and checks out the `param` source code into these virtual environments, your new code must be committed into the new feature branch locally.
To benchmark the latest commits on `main` and your new feature branch, edit `asv.conf.json` to change the line
```
"branches": ["main"],
```
into
```
"branches": ["main", "new_feature_branch"],
```
or similar.
Now when you `asv run` the benchmarks will be run against both branches in turn.
Then use
```
asv show
```
to list the commits that have been benchmarked, and
```
asv compare commit1 commit2
```
to give you a side-by-side comparison of the two commits.
You can run `asv` for single tags and compare them
```
asv run v0.0.1^!
asv run v0.0.2^!
asv compare v0.0.1 v0.0.2
```
```
asv run v0.0.2..HEAD
param-2.1.1/benchmarks/asv.conf.json 0000664 0000000 0000000 00000001544 14636363363 0017361 0 ustar 00root root 0000000 0000000 {
"version": 1,
"project": "param",
"project_url": "https://param.holoviz.org",
"repo": "..",
"dvcs": "git",
"repo_subdir": "",
"branches": ["main"],
"install_command": ["in-dir={env_dir} python -m pip install {wheel_file}"],
"uninstall_command": ["return-code=any python -m pip uninstall -y {project}"],
"build_command": [
"python -m pip install hatch hatch-vcs",
"PIP_NO_BUILD_ISOLATION=false python -mpip wheel --no-deps --no-index -w {build_cache_dir} {build_dir}"
],
"environment_type": "virtualenv",
"install_timeout": 600,
"show_commit_url": "https://github.com/holoviz/param/commit/",
// "pythons": ["3.8"],
"benchmark_dir": "benchmarks",
"env_dir": ".asv/env",
"results_dir": ".asv/results",
"html_dir": ".asv/html",
"hash_length": 8,
"build_cache_size": 2
}
param-2.1.1/benchmarks/benchmarks/ 0000775 0000000 0000000 00000000000 14636363363 0017062 5 ustar 00root root 0000000 0000000 param-2.1.1/benchmarks/benchmarks/__init__.py 0000664 0000000 0000000 00000000000 14636363363 0021161 0 ustar 00root root 0000000 0000000 param-2.1.1/benchmarks/benchmarks/benchmarks.py 0000664 0000000 0000000 00000044453 14636363363 0021563 0 ustar 00root root 0000000 0000000 # Write the benchmarking functions here.
# See "Writing benchmarks" in the asv docs for more information.
import param
class ImportSuite:
def timeraw_import_param(self):
return """
import param
"""
class ParameterSuite:
def time_instantiation(self):
param.Parameter()
class ParameterizedSuite:
def time_class_bare(self):
class P(param.Parameterized): pass
def time_class_with_1_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
def time_class_with_10_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
def time_class_with_100_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
x10 = param.Parameter()
x11 = param.Parameter()
x12 = param.Parameter()
x13 = param.Parameter()
x14 = param.Parameter()
x15 = param.Parameter()
x16 = param.Parameter()
x17 = param.Parameter()
x18 = param.Parameter()
x19 = param.Parameter()
x20 = param.Parameter()
x21 = param.Parameter()
x22 = param.Parameter()
x23 = param.Parameter()
x24 = param.Parameter()
x25 = param.Parameter()
x26 = param.Parameter()
x27 = param.Parameter()
x28 = param.Parameter()
x29 = param.Parameter()
x30 = param.Parameter()
x31 = param.Parameter()
x32 = param.Parameter()
x33 = param.Parameter()
x34 = param.Parameter()
x35 = param.Parameter()
x36 = param.Parameter()
x37 = param.Parameter()
x38 = param.Parameter()
x39 = param.Parameter()
x40 = param.Parameter()
x41 = param.Parameter()
x42 = param.Parameter()
x43 = param.Parameter()
x44 = param.Parameter()
x45 = param.Parameter()
x46 = param.Parameter()
x47 = param.Parameter()
x48 = param.Parameter()
x49 = param.Parameter()
x50 = param.Parameter()
x51 = param.Parameter()
x52 = param.Parameter()
x53 = param.Parameter()
x54 = param.Parameter()
x55 = param.Parameter()
x56 = param.Parameter()
x57 = param.Parameter()
x58 = param.Parameter()
x59 = param.Parameter()
x60 = param.Parameter()
x61 = param.Parameter()
x62 = param.Parameter()
x63 = param.Parameter()
x64 = param.Parameter()
x65 = param.Parameter()
x66 = param.Parameter()
x67 = param.Parameter()
x68 = param.Parameter()
x69 = param.Parameter()
x70 = param.Parameter()
x71 = param.Parameter()
x72 = param.Parameter()
x73 = param.Parameter()
x74 = param.Parameter()
x75 = param.Parameter()
x76 = param.Parameter()
x77 = param.Parameter()
x78 = param.Parameter()
x79 = param.Parameter()
x80 = param.Parameter()
x81 = param.Parameter()
x82 = param.Parameter()
x83 = param.Parameter()
x84 = param.Parameter()
x85 = param.Parameter()
x86 = param.Parameter()
x87 = param.Parameter()
x88 = param.Parameter()
x89 = param.Parameter()
x90 = param.Parameter()
x91 = param.Parameter()
x92 = param.Parameter()
x93 = param.Parameter()
x94 = param.Parameter()
x95 = param.Parameter()
x96 = param.Parameter()
x97 = param.Parameter()
x98 = param.Parameter()
x99 = param.Parameter()
class ParameterizedInstantiateSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
class P10(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
class P100(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
x10 = param.Parameter()
x11 = param.Parameter()
x12 = param.Parameter()
x13 = param.Parameter()
x14 = param.Parameter()
x15 = param.Parameter()
x16 = param.Parameter()
x17 = param.Parameter()
x18 = param.Parameter()
x19 = param.Parameter()
x20 = param.Parameter()
x21 = param.Parameter()
x22 = param.Parameter()
x23 = param.Parameter()
x24 = param.Parameter()
x25 = param.Parameter()
x26 = param.Parameter()
x27 = param.Parameter()
x28 = param.Parameter()
x29 = param.Parameter()
x30 = param.Parameter()
x31 = param.Parameter()
x32 = param.Parameter()
x33 = param.Parameter()
x34 = param.Parameter()
x35 = param.Parameter()
x36 = param.Parameter()
x37 = param.Parameter()
x38 = param.Parameter()
x39 = param.Parameter()
x40 = param.Parameter()
x41 = param.Parameter()
x42 = param.Parameter()
x43 = param.Parameter()
x44 = param.Parameter()
x45 = param.Parameter()
x46 = param.Parameter()
x47 = param.Parameter()
x48 = param.Parameter()
x49 = param.Parameter()
x50 = param.Parameter()
x51 = param.Parameter()
x52 = param.Parameter()
x53 = param.Parameter()
x54 = param.Parameter()
x55 = param.Parameter()
x56 = param.Parameter()
x57 = param.Parameter()
x58 = param.Parameter()
x59 = param.Parameter()
x60 = param.Parameter()
x61 = param.Parameter()
x62 = param.Parameter()
x63 = param.Parameter()
x64 = param.Parameter()
x65 = param.Parameter()
x66 = param.Parameter()
x67 = param.Parameter()
x68 = param.Parameter()
x69 = param.Parameter()
x70 = param.Parameter()
x71 = param.Parameter()
x72 = param.Parameter()
x73 = param.Parameter()
x74 = param.Parameter()
x75 = param.Parameter()
x76 = param.Parameter()
x77 = param.Parameter()
x78 = param.Parameter()
x79 = param.Parameter()
x80 = param.Parameter()
x81 = param.Parameter()
x82 = param.Parameter()
x83 = param.Parameter()
x84 = param.Parameter()
x85 = param.Parameter()
x86 = param.Parameter()
x87 = param.Parameter()
x88 = param.Parameter()
x89 = param.Parameter()
x90 = param.Parameter()
x91 = param.Parameter()
x92 = param.Parameter()
x93 = param.Parameter()
x94 = param.Parameter()
x95 = param.Parameter()
x96 = param.Parameter()
x97 = param.Parameter()
x98 = param.Parameter()
x99 = param.Parameter()
self.P1 = P1
self.P10 = P10
self.P100 = P100
def time_1_parameters(self):
self.P1()
def time_10_parameters(self):
self.P10()
def time_100_parameters(self):
self.P100()
class ParameterizedParamAccessSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
self.P1 = P1
self.p1 = P1()
def time_class(self):
self.P1.param
def time_instance(self):
self.p1.param
class ParameterizedParamContainsSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
self.P1 = P1
self.p1 = P1()
def time_class(self):
'x5' in self.P1.param
def time_instance(self):
'x5' in self.p1.param
class ParameterizedSetattrSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
self.P1 = P1
self.p1 = P1(x0=0)
def time_class(self):
self.P1.x0 = 1
def time_instance(self):
self.p1.x0 = 1
class ParameterizedDependsSuite:
def time_declarative_1_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
def time_watch_1_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
def time_declarative_10_parameters_separate_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
@param.depends('x1')
def foo1(self): pass
@param.depends('x2')
def foo2(self): pass
@param.depends('x3')
def foo3(self): pass
@param.depends('x4')
def foo4(self): pass
@param.depends('x5')
def foo5(self): pass
@param.depends('x6')
def foo6(self): pass
@param.depends('x7')
def foo7(self): pass
@param.depends('x8')
def foo8(self): pass
@param.depends('x9')
def foo9(self): pass
def time_declarative_10_parameters_shared_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9')
def foo(self): pass
def time_watch_10_parameters_separate_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
@param.depends('x1', watch=True)
def foo1(self): pass
@param.depends('x2', watch=True)
def foo2(self): pass
@param.depends('x3', watch=True)
def foo3(self): pass
@param.depends('x4', watch=True)
def foo4(self): pass
@param.depends('x5', watch=True)
def foo5(self): pass
@param.depends('x6', watch=True)
def foo6(self): pass
@param.depends('x7', watch=True)
def foo7(self): pass
@param.depends('x8', watch=True)
def foo8(self): pass
@param.depends('x9', watch=True)
def foo9(self): pass
def time_watch_10_parameters_shared_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9', watch=True)
def foo(self): pass
class ParameterizedDependsInstantiateSuite:
def setup(self):
class P1Declarative(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
class P1Watch(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
class P10DeclarativeSeparate(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
@param.depends('x1')
def foo1(self): pass
@param.depends('x2')
def foo2(self): pass
@param.depends('x3')
def foo3(self): pass
@param.depends('x4')
def foo4(self): pass
@param.depends('x5')
def foo5(self): pass
@param.depends('x6')
def foo6(self): pass
@param.depends('x7')
def foo7(self): pass
@param.depends('x8')
def foo8(self): pass
@param.depends('x9')
def foo9(self): pass
class P10DeclarativeShared(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9')
def foo(self): pass
class P10WatchSeparate(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
@param.depends('x1', watch=True)
def foo1(self): pass
@param.depends('x2', watch=True)
def foo2(self): pass
@param.depends('x3', watch=True)
def foo3(self): pass
@param.depends('x4', watch=True)
def foo4(self): pass
@param.depends('x5', watch=True)
def foo5(self): pass
@param.depends('x6', watch=True)
def foo6(self): pass
@param.depends('x7', watch=True)
def foo7(self): pass
@param.depends('x8', watch=True)
def foo8(self): pass
@param.depends('x9', watch=True)
def foo9(self): pass
class P10WatchShared(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9', watch=True)
def foo(self): pass
self.P1Declarative = P1Declarative
self.P1Watch = P1Watch
self.P10DeclarativeSeparate = P10DeclarativeSeparate
self.P10DeclarativeShared = P10DeclarativeShared
self.P10WatchSeparate = P10WatchSeparate
self.P10WatchShared = P10WatchShared
def time_declarative_1_parameter(self):
self.P1Declarative()
def time_watch_1_parameter(self):
self.P1Watch()
def time_declarative_10_parameters_separate_cb(self):
self.P10DeclarativeSeparate()
def time_declarative_10_parameters_shared_cb(self):
self.P10DeclarativeShared()
def time_watch_10_parameters_separate_cb(self):
self.P10WatchSeparate()
def time_watch_10_parameters_shared_cb(self):
self.P10WatchShared()
class WatcherSuite:
def setup(self):
class P(param.Parameterized):
x0 = param.Parameter(0)
@param.depends('x0', watch=True)
def foo0(self): pass
self.p = P()
def time_trigger(self):
self.p.x0 += 1
param-2.1.1/binder/ 0000775 0000000 0000000 00000000000 14636363363 0014073 5 ustar 00root root 0000000 0000000 param-2.1.1/binder/environment.yml 0000664 0000000 0000000 00000000167 14636363363 0017166 0 ustar 00root root 0000000 0000000 name: param
channels:
- pyviz
- defaults
dependencies:
- python=3.9.7
- aiohttp=3.7.4
- panel=0.12.4
- pip
param-2.1.1/binder/postBuild 0000664 0000000 0000000 00000000050 14636363363 0015756 0 ustar 00root root 0000000 0000000 pip uninstall param --yes
pip install .
param-2.1.1/conda.recipe/ 0000775 0000000 0000000 00000000000 14636363363 0015162 5 ustar 00root root 0000000 0000000 param-2.1.1/conda.recipe/meta.yaml 0000664 0000000 0000000 00000002102 14636363363 0016767 0 ustar 00root root 0000000 0000000 {% set pyproject = load_file_data('../pyproject.toml', from_recipe_dir=True) %}
{% set buildsystem = pyproject['build-system'] %}
{% set project = pyproject['project'] %}
{% set name = project['name'] %}
{% set version = VERSION %}
package:
name: {{ name|lower }}
version: {{ version }}
source:
path: ..
build:
noarch: python
script: {{ PYTHON }} -m pip install . -vv
requirements:
build:
- python {{ project['requires-python'] }}
- pip
{% for dep in buildsystem['requires'] %}
- {{ dep }}
{% endfor %}
run:
- python {{ project['requires-python'] }}
test:
requires:
{% for dep in project['optional-dependencies']['tests'] %}
- {{ dep }}
{% endfor %}
source_files:
- pyproject.toml
- tests
imports:
- param
- numbergen
commands:
- python -c "import param; ver = param.__version__; assert ver != '0.0.0' and ver != 'unknown'"
- pytest tests
about:
home: {{ project['urls']['Homepage'] }}
summary: {{ project['description'] }}
license: {{ project['license']['text'] }}
license_file: LICENSE.txt
param-2.1.1/doc/ 0000775 0000000 0000000 00000000000 14636363363 0013375 5 ustar 00root root 0000000 0000000 param-2.1.1/doc/Promo.ipynb 0000664 0000000 0000000 00000026233 14636363363 0015542 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "6f716cf0",
"metadata": {},
"source": [
""
]
},
{
"cell_type": "markdown",
"id": "fbaa7540",
"metadata": {},
"source": [
"# Introduction"
]
},
{
"cell_type": "markdown",
"id": "cddd48c6",
"metadata": {},
"source": [
"**Param is a library providing Parameters:** \n",
"
\n",
"\n",
"Python attributes extended to have features such as\n",
"* type and range checking\n",
"* dynamically generated values\n",
"* documentation strings\n",
"* default values\n",
"* events\n",
"
\n",
"\n",
"**Param enables you to write robust and powerful applications in just a few lines of code**.\n",
"\n",
"**Param is free, open source, small, and has no external dependencies**, so that it can easily be included as part of other projects."
]
},
{
"cell_type": "markdown",
"id": "aee0b3e3",
"metadata": {},
"source": [
"# Example: A Parameterized Class"
]
},
{
"cell_type": "markdown",
"id": "3d689222",
"metadata": {},
"source": [
"The [Pythagorean Theorem](https://en.wikipedia.org/wiki/Pythagorean_theorem) is one of the world's most famous equations.\n",
"\n",
"\n",
" \n",
"\n",
"**We will illustrate how powerful Param is** by building a model of the Pythagorean Theorem."
]
},
{
"cell_type": "markdown",
"id": "0e23597c",
"metadata": {},
"source": [
"### **Pythagorean Theorem Class**"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5e1b9718",
"metadata": {},
"outputs": [],
"source": [
"import param, math, time"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d32f4629",
"metadata": {},
"outputs": [],
"source": [
"class PythagoreanTheorem(param.Parameterized):\n",
" \"\"\"Model of the Pythagorean Theorem\"\"\"\n",
"\n",
" a = param.Number(default=0, bounds=(0,None), doc=\"Length of side a\")\n",
" b = param.Number(default=0, bounds=(0,None), doc=\"Length of side b\")\n",
" c = param.Number(default=0, bounds=(0,None), doc=\"Length of the hypotenuse c\",\n",
" constant=True)\n",
"\n",
"\n",
" def __init__(self, **params):\n",
" super().__init__(**params) # Sets values a and b if provided in the params\n",
" \n",
" self._update_hypotenuse() # Sets the value c\n",
"\n",
"\n",
" @param.depends(\"a\", \"b\", watch=True) # Triggers a run of the function whenever a or b is changed\n",
" def _update_hypotenuse(self):\n",
" \"\"\"Updates the length of the hypotenuse\"\"\"\n",
" with param.edit_constant(self):\n",
" self.c = math.sqrt(self.a**2+self.b**2)"
]
},
{
"cell_type": "markdown",
"id": "6644582b",
"metadata": {},
"source": [
"### **Pythagorean Theorem Object**"
]
},
{
"cell_type": "markdown",
"id": "90d79024",
"metadata": {},
"source": [
"**Lets try to use the model**"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "dc521631",
"metadata": {},
"outputs": [],
"source": [
"pythagoras = PythagoreanTheorem(a=3, b=4) # create an object with initial values for the parameters a and b\n",
"pythagoras.c # print the result for c"
]
},
{
"cell_type": "markdown",
"id": "f8cf6a71",
"metadata": {},
"source": [
"### **Using the Parameters**"
]
},
{
"cell_type": "markdown",
"id": "92c716bf",
"metadata": {},
"source": [
"We will now **take a closer look** at what these few lines of code provide us:"
]
},
{
"cell_type": "markdown",
"id": "3701b783",
"metadata": {},
"source": [
"#### **Param Provides Parameter Validation**"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c35d3cb2",
"metadata": {},
"outputs": [],
"source": [
"# check admissible parameter values\n",
"try:\n",
" pythagoras1 = PythagoreanTheorem(a=-1, b=4)\n",
"except Exception as ex:\n",
" print(ex)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8f4f72ac",
"metadata": {},
"outputs": [],
"source": [
"# check parameter types\n",
"try:\n",
" pythagoras2 = PythagoreanTheorem(a=\"length is 3\", b=4)\n",
"except Exception as ex:\n",
" print(ex)"
]
},
{
"cell_type": "markdown",
"id": "504d07f4",
"metadata": {},
"source": [
"Param contains a wide range of useful parameter types, including\n",
"* `String`\n",
"* `Integer`\n",
"* `Float`\n",
"* `Bool`\n",
"* `DataFrame`"
]
},
{
"cell_type": "markdown",
"id": "0a90d64b",
"metadata": {},
"source": [
"#### **Param Provides Constant Parameters**"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "47e2e544",
"metadata": {},
"outputs": [],
"source": [
"# constant values cannot be changed\n",
"try:\n",
" pythagoras.c = 3\n",
"except Exception as ex:\n",
" print(ex)"
]
},
{
"cell_type": "markdown",
"id": "7b79b3b7",
"metadata": {},
"source": [
"#### **Param Provides Default Values**"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1ea6f981",
"metadata": {},
"outputs": [],
"source": [
"print( f\"{pythagoras.param.a.name} = {pythagoras.param.a.default}\")"
]
},
{
"cell_type": "markdown",
"id": "31978876",
"metadata": {},
"source": [
"#### **Param Provides Documentation**"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5254cd8f",
"metadata": {},
"outputs": [],
"source": [
"?pythagoras"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1f403192",
"metadata": {},
"outputs": [],
"source": [
"# more extensive documentation\n",
"help(pythagoras)"
]
},
{
"cell_type": "markdown",
"id": "b2968d3e",
"metadata": {},
"source": [
"#### **Param Provides Events**"
]
},
{
"cell_type": "markdown",
"id": "c3b96a84",
"metadata": {},
"source": [
"You can **use events to react to parameter changes.**"
]
},
{
"cell_type": "markdown",
"id": "aeaddec1",
"metadata": {},
"source": [
"We have already reacted to events by using the `@param.depends(\"a\", \"b\", watch=True)` annotation \n",
"$\\quad$ to react to `a` or `b` changing by updating the calculated hypotenuse.\n",
"\n",
"Here we will use the alternative **`param.watch`** to just watch for changes to the hypotenuse `c` and print the event raised."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "92cdbf02",
"metadata": {},
"outputs": [],
"source": [
"def print_event(event):\n",
" print(event, end='\\n\\n')\n",
"\n",
"watcher = pythagoras.param.watch(print_event, \"c\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f0677602",
"metadata": {},
"outputs": [],
"source": [
"for _ in range(3):\n",
" pythagoras.b += 1\n",
" time.sleep(1)"
]
},
{
"cell_type": "markdown",
"id": "881f0acb",
"metadata": {},
"source": [
"We can also **stop watching** again:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7ff52ca7",
"metadata": {},
"outputs": [],
"source": [
"pythagoras.param.unwatch(watcher)"
]
},
{
"cell_type": "markdown",
"id": "811ee5fc",
"metadata": {},
"source": [
"## **Param Makes it Easy to Create GUIs**"
]
},
{
"cell_type": "markdown",
"id": "5cd8053b",
"metadata": {},
"source": [
"On top of param you can **quickly build interactive applications and graphical user interfaces.**"
]
},
{
"cell_type": "markdown",
"id": "2fe8fe4e",
"metadata": {},
"source": [
"The whole [HoloViz](https://holoviz.org) ecosystem is built in this way! \n",
"\n",
"
Param is a library for handling all the user-modifiable parameters, arguments, and attributes that control your code. It provides automatic, robust error-checking while dramatically reducing boilerplate code, letting you focus on what you want your code to do rather than on checking for all the possible ways users could supply inappropriate values to a function or class.
Param lets you program declaratively in Python, stating facts about each of your parameters up front. Once you have done that, Param can handle the rest (type checking, range validation, documentation, serialization, and more!).
Param-based programs tend to contain much less code than other Python programs, instead just having easily readable and maintainable manifests of Parameters for each object or function. This way your remaining code can be much simpler and clearer, while users can also easily see how to use it properly. Plus, Param doesn't require any code outside of the Python standard library, making it simple to add to any project.
Param is also useful as a way to keep your domain-specific code independent of any GUI or other user-interface code, letting you maintain a single codebase to support both GUI and non-GUI usage, with the GUI maintainable by UI experts and the domain-specific code maintained by domain experts.
To quickly see how Param works and can be used, jump straight into the [Getting Started Guide](getting_started), then check out the full functionality in the [User Guide.](user_guide/index)
```{toctree}
---
hidden: true
---
Getting Started
User Guide
API
Releases
Upgrade Guide
Comparisons
Roadmap
Developer Guide
About
```
param-2.1.1/doc/reference/ 0000775 0000000 0000000 00000000000 14636363363 0015333 5 ustar 00root root 0000000 0000000 param-2.1.1/doc/reference/index.md 0000664 0000000 0000000 00000000354 14636363363 0016766 0 ustar 00root root 0000000 0000000 # API reference
Param effectively installs two packages `param` and `numbergen` importable
under the same names. This section documents their public API.
```{toctree}
---
maxdepth: 2
---
Param
Numbergen
```
param-2.1.1/doc/reference/numbergen.md 0000664 0000000 0000000 00000000176 14636363363 0017643 0 ustar 00root root 0000000 0000000 # Numbergen API reference
```{eval-rst}
.. automodule:: numbergen
:members:
:inherited-members:
:show-inheritance:
```
param-2.1.1/doc/reference/param/ 0000775 0000000 0000000 00000000000 14636363363 0016433 5 ustar 00root root 0000000 0000000 param-2.1.1/doc/reference/param/index.md 0000664 0000000 0000000 00000001604 14636363363 0020065 0 ustar 00root root 0000000 0000000 # Param API reference
## Reactive API
```{include} reactive.md
:start-line: 2
```
## Parameterized objects
```{include} parameterized_objects.md
:start-line: 2
```
## Parameterized helpers
```{include} parameterized_helpers.md
:start-line: 2
```
## Parameters
```{include} parameters.md
:start-line: 2
```
## Parameter helpers
```{include} parameter_helpers.md
:start-line: 2
```
## `.param` namespace
```{include} param_namespace.md
:start-line: 2
```
## Logging
```{include} logging.md
:start-line: 2
```
## Serialization
```{include} serialization.md
:start-line: 2
```
```{toctree}
---
maxdepth: 2
hidden: true
---
Reactive API
Parameterized objects
Parameterized helpers
Parameters
Parameter helpers
Param namespace
Logging
Serialization
```
param-2.1.1/doc/reference/param/logging.md 0000664 0000000 0000000 00000000213 14636363363 0020377 0 ustar 00root root 0000000 0000000 # Logging
```{eval-rst}
.. autosummary::
:toctree: generated/
param.parameterized.get_logger
param.parameterized.logging_level
```
param-2.1.1/doc/reference/param/param_namespace.md 0000664 0000000 0000000 00000002216 14636363363 0022072 0 ustar 00root root 0000000 0000000 # `.param` namespace
These methods and properties are available under the `.param` namespace
of {py:class}`Parameterized` classes and instances.
```{eval-rst}
.. currentmodule:: param.parameterized
```
```{eval-rst}
.. autosummary::
:toctree: generated/
~Parameters.add_parameter
~Parameters.debug
~Parameters.defaults
~Parameters.deserialize_parameters
~Parameters.deserialize_value
~Parameters.force_new_dynamic_value
~Parameters.get_param_values
~Parameters.get_value_generator
~Parameters.inspect_value
~Parameters.log
~Parameters.message
~Parameters.method_dependencies
~Parameters.objects
~Parameters.outputs
~Parameters.params
~Parameters.params_depended_on
~Parameters.pprint
~Parameters.print_param_defaults
~Parameters.print_param_values
~Parameters.schema
~Parameters.set_default
~Parameters.set_dynamic_time_fn
~Parameters.set_param
~Parameters.serialize_parameters
~Parameters.serialize_value
~Parameters.trigger
~Parameters.unwatch
~Parameters.update
~Parameters.values
~Parameters.verbose
~Parameters.warning
~Parameters.watch
~Parameters.watch_values
~Parameters.watchers
```
param-2.1.1/doc/reference/param/parameter_helpers.md 0000664 0000000 0000000 00000000320 14636363363 0022452 0 ustar 00root root 0000000 0000000 # Parameter helpers
```{eval-rst}
.. currentmodule:: param
```
```{eval-rst}
.. autosummary::
:toctree: generated/
get_soft_bounds
guess_bounds
guess_param_types
param_union
ParamOverrides
```
param-2.1.1/doc/reference/param/parameterized_helpers.md 0000664 0000000 0000000 00000000704 14636363363 0023334 0 ustar 00root root 0000000 0000000 # Parameterized helpers
```{eval-rst}
.. currentmodule:: param
```
```{eval-rst}
.. autosummary::
:toctree: generated/
param.parameterized.Event
param.parameterized.Watcher
batch_watch
param.parameterized.batch_call_watchers
concrete_descendents
depends
discard_events
edit_constant
output
param.parameterized.register_reference_transform
param.parameterized.resolve_ref
param.parameterized.resolve_value
script_repr
```
param-2.1.1/doc/reference/param/parameterized_objects.md 0000664 0000000 0000000 00000000271 14636363363 0023322 0 ustar 00root root 0000000 0000000 # Parameterized objects
```{eval-rst}
.. currentmodule:: param
```
```{eval-rst}
.. autosummary::
:toctree: generated/
:nosignatures:
Parameterized
ParameterizedFunction
```
param-2.1.1/doc/reference/param/parameters.md 0000664 0000000 0000000 00000001015 14636363363 0021115 0 ustar 00root root 0000000 0000000 # Parameters
```{eval-rst}
.. currentmodule:: param
```
```{eval-rst}
.. autosummary::
:toctree: generated/
:nosignatures:
Parameter
String
Bytes
Color
Boolean
Event
Dynamic
Number
Integer
Magnitude
Tuple
NumericTuple
XYCoordinates
Range
Date
DateRange
CalendarDate
CalendarDateRange
List
HookList
Path
Filename
Foldername
Selector
FileSelector
ListSelector
MultiFileSelector
ClassSelector
Dict
Array
Series
DataFrame
Callable
Action
Composite
```
param-2.1.1/doc/reference/param/reactive.md 0000664 0000000 0000000 00000001123 14636363363 0020554 0 ustar 00root root 0000000 0000000 ## Reactive API
```{eval-rst}
.. currentmodule:: param
```
```{eval-rst}
.. autosummary::
:toctree: generated/
bind
rx
```
These methods and properties are available under the `.rx` namespace
of reactive expressions ({py:class}`rx`).
```{eval-rst}
.. currentmodule:: param.reactive
```
```{eval-rst}
.. autosummary::
:toctree: generated/
~reactive_ops.bool
~reactive_ops.in_
~reactive_ops.is_
~reactive_ops.is_not
~reactive_ops.len
~reactive_ops.pipe
~reactive_ops.updating
~reactive_ops.when
~reactive_ops.where
~reactive_ops.value
~reactive_ops.watch
```
param-2.1.1/doc/reference/param/serialization.md 0000664 0000000 0000000 00000000143 14636363363 0021630 0 ustar 00root root 0000000 0000000 # Serialization
```{eval-rst}
.. automodule :: param.serializer
:members:
:undoc-members:
```
param-2.1.1/doc/releases.md 0000664 0000000 0000000 00000151333 14636363363 0015530 0 ustar 00root root 0000000 0000000 # Releases
## Version 2.1.1
Date: 2024-06-25
This minor release contains bug fixes for reactive expressions and a few minor documentation improvements. Thanks to @jrycw for their first contribution! And to @ahuang11, @maximelt, and @philippjfr for their continued maintenance and development efforts.
Bug fixes:
- Ensure `rx._callback` resolves accessors ([#949](https://github.com/holoviz/param/pull/949))
- Ensure refs can be updated by watcher of the same parameter ([#929](https://github.com/holoviz/param/pull/929))
- Recursively resolve references on args and kwargs passed to a reactive operation ([#944](https://github.com/holoviz/param/pull/944))
- Only override the name of a Parameterized instance on Parameter instantiation when `instantiate=True` ([#938](https://github.com/holoviz/param/pull/938))
Documentation:
- Various minor documentation improvements ([#933](https://github.com/holoviz/param/pull/933), [#935](https://github.com/holoviz/param/pull/935), [#941](https://github.com/holoviz/param/pull/941), [#947](https://github.com/holoviz/param/pull/947))
Maintenance:
- Fix `test_reactive_logic_unary_ops` on Python 3.12 ([#946](https://github.com/holoviz/param/pull/946))
[*Full Changelog*](https://github.com/holoviz/param/compare/v2.1.0...v2.1.1)
## Version 2.1.0
Date: 2024-03-22
This minor release focuses on improving reactive expressions and support for asynchronous (and synchronous) generators. Many thanks to @maximelt, @Hoxbro and @philippjfr for their continued maintenance and development efforts.
Enhancements:
- Improvements for synchronous and asychronous generators ([#908](https://github.com/holoviz/param/pull/908))
- Additions to the .rx namespace including `and_`, `bool`, `map`, `not_`, `or_` and `updating` ([#906](https://github.com/holoviz/param/pull/906))
- Add support for adding asynchronous watcher to `rx` ([#917](https://github.com/holoviz/param/pull/917))
- Make it possible to resolve reactive expressions recursively with `.rx.resolve` ([#918](https://github.com/holoviz/param/pull/918))
- Add support for async and generator functions in `.rx.pipe` ([#924](https://github.com/holoviz/param/pull/924))
Bug fixes:
- Ensure that `.param.update` context manager restore refs ([#915](https://github.com/holoviz/param/pull/915))
- Avoid overeager root invalidation on `rx` leading to unnecessary evaluation ([#919](https://github.com/holoviz/param/pull/919))
Deprecations:
- Passing positional arguments to `Parameter` now raises a `ParamDeprecationWarning` ([#921](https://github.com/holoviz/param/pull/921))
[*Full Changelog*](https://github.com/holoviz/param/compare/v2.0.2...v2.1.0)
## Version 2.0.2
Date: 2024-01-17
This patch release fixes a few bugs and introduces a performance enhancement. Many thanks to @alfredocarella for their first contribution, and to the maintainers @maximlt and @philippjfr for contributing to this release.
Optimization:
- Minor optimizations in hot codepaths accessing class parameters ([#893](https://github.com/holoviz/param/pull/893))
Bug fixes:
- Unpack partial callables in `iscoroutinefunction` ([#894](https://github.com/holoviz/param/pull/894))
- Fix building Param with `setuptools-scm<7` ([#903](https://github.com/holoviz/param/pull/903))
Documentation:
- Replace *Google Analytics* with *GoatCounter* ([#895](https://github.com/holoviz/param/pull/895))
- Fix a typo in `Outputs.ipynb` ([#892](https://github.com/holoviz/param/pull/892))
[*Full Changelog*](https://github.com/holoviz/param/compare/v2.0.1...v2.0.2)
## Version 2.0.1
Date: 2023-11-08
This minor release fixes a number of bugs, including a regression introduced by the replacement of the build backend (`setuptools` for `hatchling`) which led to the `doc` folder being wrongly packaged. Many thanks to @SultanOrazbayev for their first contribution, to @musicinmybrain for spotting the regression and submitting fixes, and to the maintainers @Hoxbro, @jbednar and @maximlt for contributing to this release.
Bug fixes:
- Do not install `doc` folder in *site-packages* ([#878](https://github.com/holoviz/param/pull/878))
- Drop the `feather-format` test dependency ([#879](https://github.com/holoviz/param/pull/879))
- Add `tables` to the `tests-deser` extra ([#880](https://github.com/holoviz/param/pull/880))
- Fix `_state_push` and `_state_pop` ([#884](https://github.com/holoviz/param/pull/884))
- `version.py`: new process should not create a window on Windows ([#882](https://github.com/holoviz/param/pull/882), [#886](https://github.com/holoviz/param/pull/886))
- Don't import `setuptools_scm` if the `.git` folder doesn't exist ([#885](https://github.com/holoviz/param/pull/885))
Documentation:
- Add migration guide to Param 2.0 ([#883](https://github.com/holoviz/param/pull/883))
- Update Parameter API reference ([#881](https://github.com/holoviz/param/pull/881))
[*Full Changelog*](https://github.com/holoviz/param/compare/v2.0.0...v2.0.1)
## Version 2.0.0
Date: 2023-10-24
20 years after its creation, Param has reached version 2.0! Can you guess when Param 3.0 will be released?
Param 2.0 is a major new release available for Python 3.8 and above, significantly streamlining, simplifying, and improving the Param API. Many long-supported but also long-obsolete functions, methods, and usages will now warn loudly so that you can make sure your code is only using the fully supported and safe current approaches. Because upgrading to Param 2 is likely to reveal compatibility issues with older codebases, new releases in the 1.x series are expected to continue for some time, focused on compatibility with the ecosystem rather than adding new features. Thus you can keep using Param 1.x with your older code, but Param 2 is the future!
We would like to thank @minimav for their first contribution, and @droumis, @Hoxbro, @jbednar, @maximlt, @philippjfr and @sdrobert for their contributions. We would also like to thank @ceball, who made the first plans for Param 2.0 quite a few years ago, and we are glad to be delivering on them at last!
### Major enhancements and features
- Parameter slot values are now all inherited correctly across a hierarchy of Parameterized classes, making their behavior much clearer and more consistent. Let's say we have class `B` being a subclass of `A`, itself being a subclass of `param.Parameterized`. If `A` defines `x = Number(1, bounds=(0, 10))` and `B` defines `x = Number(2)`, `B.param['x'].bounds` is now going to be inherited from `A` and equal to `(0, 10)` as you would expect. Parameterized classes have always supported inheritance, but the previous mechanism was based on using `None` to indicate which values should be inherited, which was highly problematic because `None` was also a valid value for many slots. All Parameter slot signatures now default to the new `Undefined` sentinel, finally allowing `None` to be inherited where appropriate. ([#605](https://github.com/holoviz/param/pull/605), [#771](https://github.com/holoviz/param/pull/771), [#791](https://github.com/holoviz/param/pull/791), [#874](https://github.com/holoviz/param/pull/874))
- The `objects` slot of a Selector was previously highly confusing, because it accepted either a dictionary or a list for initialization but then was accessible only as a list, making it difficult to watch or update the objects. There is now a `ListProxy` wrapper around `Selector.objects` (with forward and backward compatibility) to easily update `objects` and watch `objects` updates ([#598](https://github.com/holoviz/param/pull/598), [#825](https://github.com/holoviz/param/pull/825))
- Parameterized classes and instances now have a rich HTML representation that is displayed automatically in a Jupyter/IPython notebook. For a class or instance `p`, just return `p.param` in a notebook cell to see a table of all the Parameters of the class/instance, their state, type, and range, plus the docstring on hover. It is likely we will improve the content and design of this repr based on feedback, so please let us know what you think! ([#425](https://github.com/holoviz/param/pull/425), [#781](https://github.com/holoviz/param/pull/781), [#821](https://github.com/holoviz/param/pull/821), [#831](https://github.com/holoviz/param/pull/831))
- Parameters have all gained the `allow_refs` and `nested_refs` attributes, bringing an exceptionally useful feature that was available in Panel since version 1.2 to Param. Declaring a Parameter with `allow_refs=True` (`False` by default) allows setting this Parameter value with a *reference* to automatically mirror the value of the reference. Supported references include class/instance Parameter objects, functions/methods decorated with `param.depends`, reactive functions and expressions, asynchronous generators and custom objects transformed into a valid reference with a hook registered with `param.parameterized.register_reference_transform`. `nested_refs` indicate whether references should be resolved even when they are nested inside a container ([#843](https://github.com/holoviz/param/pull/843), [#845](https://github.com/holoviz/param/pull/845), [#849](https://github.com/holoviz/param/pull/849), [#865](https://github.com/holoviz/param/pull/865), [#862](https://github.com/holoviz/param/pull/862), [#876](https://github.com/holoviz/param/pull/876))
- Experimental new `rx` reactive expressions: Param is widely used for building web apps in the HoloViz ecosystem, where packages have added various mechanisms for dynamic updates (e.g. `pn.bind` and `pn.depends` in Panel, and `.interactive` in hvPlot). These mechanisms were already built on Param and can be used far more widely than just in those packages, so that functionality has now been generalized, streamlined, and moved into Param. Nearly any Python expression can now be made reactive with `param.rx()`, at which point it will collect and be able to replay any operations (e.g. method calls) performed on them. This reactive programming approach lets you take just about any existing Python workflow and replace attributes with widgets or other reactive values, creating an app with fine-grained user control without having to design callbacks, event handlers, or any other complex logic! `rx` support is still experimental while we get feedback about the API, packaging, and documentation, but it's fully ready to try out and give us suggestions!
([#460](https://github.com/holoviz/param/pull/460), [#842](https://github.com/holoviz/param/pull/842), [#841](https://github.com/holoviz/param/pull/841), [#844](https://github.com/holoviz/param/pull/844), [#846](https://github.com/holoviz/param/pull/846), [#847](https://github.com/holoviz/param/pull/847), [#850](https://github.com/holoviz/param/pull/850), [#851](https://github.com/holoviz/param/pull/851), [#856](https://github.com/holoviz/param/pull/856), [#860](https://github.com/holoviz/param/pull/860), [#854](https://github.com/holoviz/param/pull/854), [#859](https://github.com/holoviz/param/pull/859), [#858](https://github.com/holoviz/param/pull/858), [#873](https://github.com/holoviz/param/pull/873))
### Enhancements
- Parameter slot values that are set to mutable containers (e.g. `Selector(objects=a_list)`) will now be shallow-copied on instantiation, so that the container is no longer confusingly shared between the class and its subclasses and instances ([#826](https://github.com/holoviz/param/pull/826))
- To further clean up the Parameterized namespace (first started in version 1.7.0), the remaining private attributes haven been collected under two private namespaces `_param__private` and `_param__parameters` ([#766](https://github.com/holoviz/param/pull/766), [#790](https://github.com/holoviz/param/pull/790))
- You can now use `.param.update` as a context manager for applying temporary updates ([#779](https://github.com/holoviz/param/pull/779))
- The `name` Parameter has always had special behavior dating to its use in labeling objects in a GUI context, but this behavior is now able to be overriden at the class and instance level ([#740](https://github.com/holoviz/param/pull/740))
- Improved Parameter signatures for static and dynamic code analysis ([#742](https://github.com/holoviz/param/pull/742))
- Removed inferred Parameterized docstring signature and add basic `__signature__` support ([#802](https://github.com/holoviz/param/pull/802))
- For speed, only generate the Parameter docstring in an IPython context ([#774](https://github.com/holoviz/param/pull/774))
- Improve Parameter validation error messages ([#808](https://github.com/holoviz/param/pull/808))
- Support for deserialization of file types into `Array` and `DataFrame` ([#482](https://github.com/holoviz/param/pull/482))
- `Integer` now accepts `numpy.integer` values ([#735](https://github.com/holoviz/param/pull/735))
- `Range` now does stricter validation of the slot values ([#725](https://github.com/holoviz/param/pull/725), [#824](https://github.com/holoviz/param/pull/824))
- `Path` now has `check_exists` attribute, leading it to raise an error if `path` is not found on parameter instantiation ([#800](https://github.com/holoviz/param/pull/800))
- Add top-level `__all__` and move Parameter classes to `parameters.py` ([#853](https://github.com/holoviz/param/pull/853))
### Bug fixes
- Allow type change for `DateRange` and `Date` ([#733](https://github.com/holoviz/param/pull/733))
- Ensure class watchers are not inherited by instance parameter ([#833](https://github.com/holoviz/param/pull/833))
- Fix multi-level indirection in Parameters access ([#840](https://github.com/holoviz/param/pull/840))
- Ensure non-function types are not resolved as empty function declarations ([#753](https://github.com/holoviz/param/pull/753))
- Fix watchers support when the Parameterized instance is falsy ([#769](https://github.com/holoviz/param/pull/769))
- Fix depending on the method of a sub-parameter object ([#765](https://github.com/holoviz/param/pull/765))
- Raise an error on bad non-watched references ([#777](https://github.com/holoviz/param/pull/777))
- Ensure that the root dependency can be resolved, and error otherwise ([#813](https://github.com/holoviz/param/pull/813))
- Fix basic pickling ([#783](https://github.com/holoviz/param/pull/783), [#792](https://github.com/holoviz/param/pull/792))
- Validate that `self` is present in the `__init__` signature of a Parameterized class ([#786](https://github.com/holoviz/param/pull/786))
- No longer force `instantiate` to True when `constant` is True ([#776](https://github.com/holoviz/param/pull/776))
- Instantiate default Parameter values based on all the Parameters available ([#798](https://github.com/holoviz/param/pull/798))
- `Array`: fix `param.pprint` ([#795](https://github.com/holoviz/param/pull/795))
- `Array`: don't hard-code `allow_None` to `True` ([#726](https://github.com/holoviz/param/pull/726))
- `Boolean`: validate the default type ([#722](https://github.com/holoviz/param/pull/722))
- `FileSelector`: made more consistent with `Selector` by defaulting to the first globbed path ([#801](https://github.com/holoviz/param/pull/801))
- `FileSelector`: ensure path separators are consistent on Windows ([#805](https://github.com/holoviz/param/pull/805))
- `Path`: raise a `ValueError` if set to `None` while not allowed ([#799](https://github.com/holoviz/param/pull/799))
- `Selector`: populate `objects` when `check_on_set` is False and `default` is not in `objects` ([#794](https://github.com/holoviz/param/pull/794), [#817](https://github.com/holoviz/param/pull/817))
- `File/MultiFileSelector`: updating `path` updates `objects` ([#814](https://github.com/holoviz/param/pull/814))
### Documentation
- Build the site with `sphinx` directly and refactor the API reference ([#810](https://github.com/holoviz/param/pull/810))
- Update to the latest version of `pydata-sphinx-theme` ([#752](https://github.com/holoviz/param/pull/752))
- Update to Google Analytics 4 ([#758](https://github.com/holoviz/param/pull/758))
- Fix minor errors in the Getting Started ([#787](https://github.com/holoviz/param/pull/787))
- Add OpenCollective sponsor link on the repository page ([#811](https://github.com/holoviz/param/pull/811))
### Infrastructure
- Increase the test suite coverage ([#716](https://github.com/holoviz/param/pull/716), [#717](https://github.com/holoviz/param/pull/717), [#719](https://github.com/holoviz/param/pull/719), [#720](https://github.com/holoviz/param/pull/720), [#739](https://github.com/holoviz/param/pull/739), [#775](https://github.com/holoviz/param/pull/775), [#778](https://github.com/holoviz/param/pull/778))
- Turn warnings into exceptions in the test suite ([#738](https://github.com/holoviz/param/pull/738))
- Add notebook smoke tests ([#750](https://github.com/holoviz/param/pull/750))
- Upgrades to leverage `hatch`, `pyproject.toml` and `pre-commit` ([#749](https://github.com/holoviz/param/pull/749), [#772](https://github.com/holoviz/param/pull/772))
- Add basic benchmark suite using `asv` ([#788](https://github.com/holoviz/param/pull/788))
- Reduce the number of tested Python versions ([#732](https://github.com/holoviz/param/pull/732))
- Run the tests with Python 3.12 ([#863](https://github.com/holoviz/param/pull/863))
### Compatibility
- Drop support for Python 2.7, 3.6, and 3.7 and upgrade the code base accordingly ([#741](https://github.com/holoviz/param/pull/741), [#784](https://github.com/holoviz/param/pull/784))
### Breaking changes
- While it's a major improvement to the definition of Parameters, properly inheriting Parameter slots can result in some Parameter slot values being different in Param 2, because Param 1 was sometimes silently not inheriting slot values.
- User-defined `Parameter` classes should be updated to use `Undefined` as the formal default for any new slots, with the actual default defined on the new `_slot_defaults` dictionary. Otherwise, any new slot will fail to support inheritance, even if it was set to `None`, which would previously support inheritance.
- `Parameterized` methods that were deprecated since Param 1.7.0 have finally been removed. These are now mostly available on the `.param` namespace ([#592](https://github.com/holoviz/param/pull/592))
- No longer supports setting non-Parameter class attributes during initialization, and no longer warns when setting non-Parameter class attributes directly ([#729](https://github.com/holoviz/param/pull/729))
- `instance.param.watchers` no longer returns the transient dict of watchers but instead returns the instance watchers, as the now deprecated `instance._param_watchers` ([#797](https://github.com/holoviz/param/pull/797))
- Removed deprecated `Parameterized.pprint`, `Parameterized._pprint`, `Parameterized.script_repr`, `ParameterizedFunction.script_repr` ([#767](https://github.com/holoviz/param/pull/767))
- Removed `Time.next` method needed only for Python 2, and moved `Parameterized.state_pop` and `Parameterized.state_push` to the `.param` namespace ([#767](https://github.com/holoviz/param/pull/767))
- Some removals were considered harmless and thus implemented immediately without a deprecation period:
- Removed unused `bounds` slot from `Boolean` and `Event` ([#744](https://github.com/holoviz/param/pull/744), [#755](https://github.com/holoviz/param/pull/755))
- Removed private Parameter `_internal_name` slot ([#796](https://github.com/holoviz/param/pull/796))
### Deprecations
This section lists functionality that is expected to be removed sometime in the next couple of 2.x releases, so if you use Param 2, please take care of these warnings as soon as you encounter them, and certainly before you upgrade to the next release!
Param 2.0 adds a validation step of the *default* value of a Parameter after the inheritance mechanism has completed if its type has changed (e.g. `x` in class `A` is a `Number` and in class `B(A)` is an `Integer`) or one of its slot values has changed ([#812](https://github.com/holoviz/param/pull/812), [#820](https://github.com/holoviz/param/pull/820), [#857](https://github.com/holoviz/param/pull/857)). We have decided to only emit a warning when this validation fails to make your life easier when upgrading your code from Param 1 to 2, as the validation is performed on class creation which means that any validation error breaks importing your code. You should definitely take care of these warnings, they indicate a Parameter is in an invalid state!
We continue to clean up Param's API ([#734](https://github.com/holoviz/param/pull/734), [#751](https://github.com/holoviz/param/pull/751), [#768](https://github.com/holoviz/param/pull/768), [#797](https://github.com/holoviz/param/pull/797), [#834](https://github.com/holoviz/param/pull/834), [#838](https://github.com/holoviz/param/pull/838)) but have decided to do it in a gentle way, emitting deprecation warnings for a period of time before proceeding with removals. You will find below the complete list of deprecation warnings added in Param 2.0.
- Parameter signature:
- Instantiating most parameters with positional arguments beyond `default` is deprecated:
- `String('prefix-test', '^prefix')`: deprecated!
- `String('prefix-test', regex='^prefix')`: OK
- `String(default='prefix-test', regex='^prefix')`: OK
- For `Selector` parameters that accept `objects` as first positional argument, and `ClassSelector` parameters that accept `class_` as first positional argument, passing any argument by position is deprecated:
- `Selector([1, 2])`: deprecated!
- `Selector(objects=[1, 2])`: OK
- `ClassSelector((str, int))`: deprecated!
- `ClassSelector(class_=(str, int))`: OK
- It's possible that in the future the signature of these two parameters will be aligned with the other parameters to accept `default` as first and only positional argument, but for now please use an explicit keyword so that your code will be compatible with all versions.
- Parameter slots:
- `List._class`: use instead `item_type`.
- `Number.set_hook`: no replacement
- `param.__init__` module:
- `param.produce_value`: no replacement
- `param.as_unicode`: no replacement
- `param.is_ordered_dict`: no replacement
- `param.is_ordered_dict`: no replacement
- `param.hashable`: no replacement
- `param.named_objs`: no replacement
- `param.normalize_path`: no replacement
- `param.abbreviate_paths`: no replacement
- `param.parameterized` module:
- `param.parameterized.all_equal`: no replacement
- `param.parameterized.add_metaclass`: no replacement
- `param.parameterized.batch_watch`: use instead `batch_call_watchers`
- `param.parameterized.recursive_repr`: no replacement
- `param.parameterized.overridable_property`: no replacement
- Parameterized `.param` namespace; many of these methods have been deprecated since version 1.12.0, however, this was just announced in the release notes and we realised many users missed them, sometimes even us included! They now all emit deprecation warnings when executed and are clearly marked as deprecated in the API reference:
- `.param.set_default`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `.param._add_parameter`: use instead `.param.add_parameter`
- `.param.params`: use instead `.param.values()` or `.param['param']`
- `.param.set_param`: use instead `.param.update`
- `.param.get_param_values`: use instead `.param.values().items()` (or `.param.values()` for the common case of `dict(....param.get_param_values())`)
- `.param.params_depended_on`: use instead `.param.method_dependencies`
- `.param.defaults`: use instead `{k:v.default for k,v in p.param.objects().items()}`
- `.param.print_param_defaults`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `.param.print_param_values`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `.param.message`: use instead `.param.log(param.MESSAGE, ...)`
- `.param.verbose`: use instead `.param.log(param.VERBOSE, ...)`
- `.param.debug`: use instead `.param.log(param.DEBUG, ...)`
- Running unsafe operations **during Parameterized instance initialization**, instead run these operations after having called `super().__init__(**params)`:
- `instance.param.objects(instance=True)`
- `instance.param.trigger("")`
- `instance.param.watch(callback, "")`
- Parameterized namespace:
- `instance._param_watchers` (getter and setter): use instead the property `inst.param.watchers`
[*Full Changelog*](https://github.com/holoviz/param/compare/v1.13.0...v2.0.0)
## Version 1.13.0
Date: 2023-03-14
The `1.13.0` is the last release of Param before the 2.0 release. However, Param 1.13 is meant to receive long-term support; security patches and fixes to critical bugs are planned to be backported to the 1.13.x series.
This release includes a new `Bytes` *Parameter* and a few important bug fixes. This release is also marked by the adoption of a formal project governance, ensuring Param's future as a healthy open-source project. Many thanks to @ovidner and @droumis for their first contributions! And to @maximlt, @Hoxbro, @jlstevens, @philippjfr and @jbednar for their continuing support to fixing and improving Param.
Bug fixes:
* Fix copying when having watchers on e.g. bounds on inherited Parameter types ([#675](https://github.com/holoviz/param/pull/675))
* Allow JSON serialization to work with `json.dumps` ([#655](https://github.com/holoviz/param/pull/655))
* `ListSelector` restricted to `list` type objects ([#531](https://github.com/holoviz/param/pull/531))
* Fix `depends` async wrapper ([#684](https://github.com/holoviz/param/pull/684))
* Allow named colors to be any case ([#711](https://github.com/holoviz/param/pull/711))
New features:
* Add Bytes parameter ([#542](https://github.com/holoviz/param/pull/542))
Documentation:
* Fix param module link ([#682](https://github.com/holoviz/param/pull/682))
Project governance:
* Create initial project governance docs ([#674](https://github.com/holoviz/param/pull/674))
Maintenance:
* Rename `master` branch to `main` ([#672](https://github.com/holoviz/param/pull/672))
* Add more tests ([#710](https://github.com/holoviz/param/pull/710))
* Various CI related fixes ([#680](https://github.com/holoviz/param/pull/680), [#683](https://github.com/holoviz/param/pull/683) and [#709](https://github.com/holoviz/param/pull/709))
## Version 1.12.3
Date: 2022-12-06
The `1.12.3` release adds support for Python 3.11. Many thanks to @musicinmybrain (first contribution!) and @maximlt for contributing to this release.
Enhancements:
* Preserve existing Random seed behavior in Python 3.11 ([#638](https://github.com/holoviz/param/pull/638))
* Add support for Python 3.11 ([#658](https://github.com/holoviz/param/pull/658))
## Version 1.12.2
Date: 2022-06-14
The `1.12.2` release fixes a number of bugs and adds support again for Python 2.7, which was unfortunately no longer supported in the last release. Note however that Param 2.0 will still drop support of Python 2.7 as already announced. Many thanks to @Hoxbro and the maintainers @jbednar, @jlstevens, @maximlt and @philippjfr for contributing to this release.
Bug fixes:
* Match against complete spec name when determining dynamic watchers ([#615](https://github.com/holoviz/param/pull/615))
* Ensure async functionality does not cause python2 syntax errors ([#624](https://github.com/holoviz/param/pull/624))
* Allow (de)serializing `CalendarRange` and `DateRange` `Parameters` ([#625](https://github.com/holoviz/param/pull/625))
* Improve `DateRange` validation ([#627](https://github.com/holoviz/param/pull/627))
* Fix regression in `@param.depends` execution ordering ([#628](https://github.com/holoviz/param/pull/628))
* Ensure `named_objs` does not fail on unhashable objects ([#632](https://github.com/holoviz/param/pull/632))
* Support comparing date-like objects ([#629](https://github.com/holoviz/param/pull/629))
* Fixed `BinaryPower` example in the docs to use the correct name `EvenInteger`([#634](https://github.com/holoviz/param/pull/634))
## Version 1.12.1
The 1.12.1 release fixes a number of bugs related to async callback handling when using `param.depends` and `.param.watch` and a number of documentation and error messages. Many thanks to @HoxBro and the maintainers @jbednar, @jlstevens, @maximlt and @philippjfr for contributing to this release.
Error handling and documentation:
- Fixed description of shared_parameters ([#568](https://github.com/holoviz/param/pull/568))
- Improve the error messages of Date and DateRange ([#579](https://github.com/holoviz/param/pull/579))
- Clarified step error messages and other docs and links ([#604](https://github.com/holoviz/param/pull/604))
Bug fixes:
- Make iscoroutinefunction more robust ([#572](https://github.com/holoviz/param/pull/572))
- Fix for handling misspelled parameter ([#575](https://github.com/holoviz/param/pull/575))
- Handle None serialization for Date, CalendarDate, Tuple, Array, and DataFrame ([#582](https://github.com/holoviz/param/pull/582))
- Support async coroutines in param.depends ([#591](https://github.com/holoviz/param/pull/591))
- Handle async functions in depends with watch=True ([#611](https://github.com/holoviz/param/pull/611))
- Avoid equality check on Watcher ([#612](https://github.com/holoviz/param/pull/612))
Documentation:
- Fix binder ([#564](https://github.com/holoviz/param/pull/564))
- Fixed description of shared_parameters ([#568](https://github.com/holoviz/param/pull/568))
## Version 1.12.0
Version 1.12.0 introduces a complete user manual and website (for the first time since 2003!) along with extensive API improvements gearing up for the 2.0 release (which will be Python3 only).
The pre-2.0 API is still being preserved and no new warnings are added in this release, so the older API can continue to be used with this release, but the next 1.x release is expected to enable warnings for deprecated API. If you have older code using the deprecated Param features below, please update your API calls as described below to be compatible with the 2.0 release when it comes out (or pin to param<2 if you don't need any new Param features). For new users, just use the API documented on the website, and you should be ready to go for either 1.12+ or 2.0+.
Thanks to James A. Bednar for the user guide and 2.0 API support, to Philipp Rudiger for improvements and new capabilities for handling dependencies on subobjects, and to Maxime Liquet and Philipp Rudiger for extensive improvements to the website/docs/package-building/testing.
New features:
- Added future-facing API for certain Parameterized().param methods (see Compatibility below; [#556](https://github.com/holoviz/param/pull/556), [#558](https://github.com/holoviz/param/pull/558), [#559](https://github.com/holoviz/param/pull/559))
- New option `on_init=True` for `@depends` decorator, to run the method in the constructor to ensure initial state is consistent when appropriate ([#540](https://github.com/holoviz/param/pull/540))
- Now resolves subobject dependencies dynamically, allowing dependencies on internal parameters of subobjects to resolve appropriately as those objects are replaced. ([#552](https://github.com/holoviz/param/pull/552))
- Added prettyprinting for numbergen expressions ([#525](https://github.com/holoviz/param/pull/525))
- Improved JSON schema generation ([#458](https://github.com/holoviz/param/pull/458))
- Added more-usable script_repr command, availabie in param namespace, with default values, and showing imports ([#522](https://github.com/holoviz/param/pull/522))
- Added Parameterized.param.pprint(); underlying implementation of script_repr but with defaults suitable for interactive usage rather than generating a .py script. ([#522](https://github.com/holoviz/param/pull/522))
- Watchers can now declare precedence so that events are triggered in the desired order ([#552](https://github.com/holoviz/param/pull/552), [#557](https://github.com/holoviz/param/pull/557))
Bug fixes:
- Fix bug setting attributes in some cases before class is initialized ([#544](https://github.com/holoviz/param/pull/544))
- Ensure None is supported on ListSelector ([#511](https://github.com/holoviz/param/pull/511))
- Switched from deprecated `inspect.getargspec` to the py3 version `inspect.getfullargspec`, which is similar but splits `keyword` args into `varkw` (**) and kw-only args. Falls back to getargspec on Python2. ([#521](https://github.com/holoviz/param/pull/521))
Doc improvements (including complete user guide for the first time!):
- Misc comments/docstrings/docs cleanup ([#507](https://github.com/holoviz/param/pull/507), [#518](https://github.com/holoviz/param/pull/518), [#528](https://github.com/holoviz/param/pull/528), [#553](https://github.com/holoviz/param/pull/553))
- Added comparison with pydantic ([#523](https://github.com/holoviz/param/pull/523))
- Added new user guide sections:
* Dependencies_and_Watchers user guide ([#536](https://github.com/holoviz/param/pull/536))
* Dynamic Parameters ([#525](https://github.com/holoviz/param/pull/525))
* Outputs ([#523](https://github.com/holoviz/param/pull/523))
* Serialization and Persistence ([#523](https://github.com/holoviz/param/pull/523))
Infrastructure:
- Added testing on Python 3.10 and on Mac OS X and removed slow PyPy/pandas/numpy tests ([#548](https://github.com/holoviz/param/pull/548), [#549](https://github.com/holoviz/param/pull/549), [#526](https://github.com/holoviz/param/pull/526))
- Docs/tests/build infrastructure improvements ([#509](https://github.com/holoviz/param/pull/509), [#521](https://github.com/holoviz/param/pull/521), [#529](https://github.com/holoviz/param/pull/529), [#530](https://github.com/holoviz/param/pull/530), [#537](https://github.com/holoviz/param/pull/537), [#538](https://github.com/holoviz/param/pull/538), [#539](https://github.com/holoviz/param/pull/539), [#547](https://github.com/holoviz/param/pull/547), [#548](https://github.com/holoviz/param/pull/548), [#555](https://github.com/holoviz/param/pull/555))
Compatibility (see [#543](https://github.com/holoviz/param/pull/543) for the complete list):
- Calendardate now accepts date values only ([#517](https://github.com/holoviz/param/pull/517))
- No longer allows modifying name of a Parameter once it is in a Parameterized class, to avoid confusion ([#541](https://github.com/holoviz/param/pull/541))
- Renamed (with old name still accepted for compatibility until 2.0):
* `.param._add_parameter()`: Now public `.param.add_parameter()`; too useful to keep private! ([#559](https://github.com/holoviz/param/pull/559))
* `.param.params_depended_on`: Now `.param.method_dependencies` to indicate that it accepts a method name and returns its dependencies ([#559](https://github.com/holoviz/param/pull/559))
* `.pprint`: Now private `._pprint`; use public `.param.pprint` instead ([#559](https://github.com/holoviz/param/pull/559))
* `batch_watch`: Now `batch_call_watchers`, to declare that it does not set up watching, it just invokes it. Removed unused operation argument ([#536](https://github.com/holoviz/param/pull/536))
- Deprecated (but not yet warning unless noted):
* `.param.debug()`: Use `.param.log(param.DEBUG, ...)` instead ([#556](https://github.com/holoviz/param/pull/556))
* `.param.verbose()`: Use `.param.log(param.VERBOSE, ...)` instead ([#556](https://github.com/holoviz/param/pull/556))
* `.param.message()`: Use `.param.log(param.MESSAGE, ...)` instead ([#556](https://github.com/holoviz/param/pull/556))
* `.param.defaults()`: Use `{k:v.default for k,v in p.param.objects().items()}` instead ([#559](https://github.com/holoviz/param/pull/559))
* `.param.deprecate()`: To be repurposed or deleted after 2.0 ([#559](https://github.com/holoviz/param/pull/559))
* `.param.params()`: Use `.param.values()` or `.param['param']` instead ([#559](https://github.com/holoviz/param/pull/559))
* `.param.print_param_defaults()`: Use `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")` instead ([#559](https://github.com/holoviz/param/pull/559))
* `.param.print_param_values()`: Use `for k,v in p.param.values().items(): print(f"{p.name}.{k}={v}")` instead ([#559](https://github.com/holoviz/param/pull/559))
* `.param.set_default()`: Use `p.param.default=` instead ([#559](https://github.com/holoviz/param/pull/559))
* `.param.set_param()`: Had tricky API; use `.param.update` instead ([#558](https://github.com/holoviz/param/pull/558))
* `.param.get_param_values()`: Use `.param.values().items()` instead (or `.param.values()` for the common case of `dict(....param.get_param_values())`) ([#559](https://github.com/holoviz/param/pull/559))
* `.state_pop()`: Will be renamed to `._state_pop` to make private
* `.state_push()`: Will be renamed to `._state_push` to make private
* `.initialized`: Will be renamed to `._initialized` to make private
* Most methods on Parameterized itself have already been deprecated and warning for some time now; see [#543](https://github.com/holoviz/param/pull/543) for the list. Use the corresponding method on the `.param` accessor instead.
- Added:
* `.param.watchers`: Read-only version of private `_watchers` ([#559](https://github.com/holoviz/param/pull/559))
* `.param.log()`: Subsumes .debug/verbose/message; all are logging calls. ([#556](https://github.com/holoviz/param/pull/556))
* `.param.update()`: Dictionary-style updates to parameter values, as a drop-in replacement for `set_param` except for its optional legacy positional-arg syntax ([#558](https://github.com/holoviz/param/pull/558))
* `.values()`: Dictionary of name:value pairs for parameter values, replacing `get_param_values` but now a dict since python3 preserves order ([#558](https://github.com/holoviz/param/pull/558))
* `.param.log()`: General-purpose interface to the logging module functionailty; replaces .debug, .verbose, .message ([#556](https://github.com/holoviz/param/pull/556))
## Version 1.11.1
(including changes in 1.11.0; 1.11.1 adds only a minor change to fix `param.List(None)`.)
Version 1.11 contains entirely new [documentation](https://param.holoviz.org), plus various enhancements and bugfixess. Thanks to James A. Bednar for the documentation, Philipp Rudiger for the website setup and for many of the other fixes and improvements below, and others as noted below.
Documentation:
- Brand-new website, with getting started, user manual, reference manual, and more! Some user guide sections are still under construction. ([#428](https://github.com/holoviz/param/pull/428),[#464](https://github.com/holoviz/param/pull/464),[#479](https://github.com/holoviz/param/pull/479),[#483](https://github.com/holoviz/param/pull/483),[#501](https://github.com/holoviz/param/pull/501),[#502](https://github.com/holoviz/param/pull/502),[#503](https://github.com/holoviz/param/pull/503),[#504](https://github.com/holoviz/param/pull/504))
- New intro video with examples/Promo.ipynb notebook, thanks to Marc Skov Madsen and Egbert Ammicht ([#488](https://github.com/holoviz/param/pull/488))
- Sort docstring by definition order and precedence, thanks to Andrew Huang ([#445](https://github.com/holoviz/param/pull/445))
Enhancements:
- Allow printing representations for recursively nested Parameterized objects ([#499](https://github.com/holoviz/param/pull/499))
- Allow named colors for param.Color ([#472](https://github.com/holoviz/param/pull/472))
- Allow FileSelector and MultiFileSelector to accept initial values ([#497](https://github.com/holoviz/param/pull/497))
- Add Step slot to Range, thanks to Simon Hansen ([#467](https://github.com/holoviz/param/pull/467))
- Update FileSelector and MultiFileSelector parameters when setting path ([#476](https://github.com/holoviz/param/pull/476))
- Improved error messages ([#475](https://github.com/holoviz/param/pull/475))
Bug Fixes:
- Fix Path to allow folders, as documented but previously not supported ([#495](https://github.com/holoviz/param/pull/495))
- Fix previously unimplemented Parameter._on_set ([#484](https://github.com/holoviz/param/pull/484))
- Fix Python2 IPython output parameter precedence ([#477](https://github.com/holoviz/param/pull/477))
- Fix allow_None for param.Series and param.DataFrame ([#473](https://github.com/holoviz/param/pull/473))
- Fix behavior when both `instantiate` and `constant` are `True` ([#474](https://github.com/holoviz/param/pull/474))
- Fix for versioning when param is inside a separate git-controlled repo (port of fix from autover/pull/67) ([#469](https://github.com/holoviz/param/pull/469))
Compatibility:
- Swapped ObjectSelector and Selector in the inheritance hierarchy, to allow ObjectSelector to be deprecated. ([#497](https://github.com/holoviz/param/pull/497))
- Now `get_soft_bounds`silently crops softbounds to any hard bounds supplied ; previously soft bounds would be returned even if they were outside the hard bounds ([#498](https://github.com/holoviz/param/pull/498))
- Rename `class_` to `item_type` in List parameter, to avoid clashing semantics with ClassSelector and others with a `class_` slot. `class_` is still accepted as a keyword but is stored in `item_type`. ([#456](https://github.com/holoviz/param/pull/456))
## Version 1.10.1
Minor release for Panel-related bugfixes and minor features, from @philippjfr.
- Fix serialization of Tuple, for use in Panel ([#446](https://github.com/holoviz/param/pull/446))
- Declare asynchronous executor for Panel to use ([#449](https://github.com/holoviz/param/pull/449))
- Switch to GitHub Actions ([#450](https://github.com/holoviz/param/pull/450))
## Version 1.10.0
## Version 1.9.3
- Fixed ClassSelector.get_range when a tuple of types is supplied ([#360](https://github.com/holoviz/param/pull/360))
## Version 1.9.2
- Compatibility with Python 3.8
- Add eager option to watch calls ([#351](https://github.com/holoviz/param/pull/351))
- Add Calendar and CalendarDateRange for real date types ([#348](https://github.com/holoviz/param/pull/348))
## Version 1.9.1
Enhancements:
- Allow param.depends to annotate functions ([#334](https://github.com/holoviz/param/pull/334))
- Add context managers to manage events and edit constant parameters
Bug fixes:
- Ensure that Select constructor does not rely on truthiness ([#337](https://github.com/holoviz/param/pull/337))
- Ensure that param.depends allows mixed Parameter types ([#338](https://github.com/holoviz/param/pull/338))
- Date and DateRange now allow dt.date type ([#341](https://github.com/holoviz/param/pull/341))
- Ensure events aren't dropped in batched mode ([#343](https://github.com/holoviz/param/pull/343))
## Version 1.9.0
Full release with new functionality and some fixes. New features:
- Added support for instance parameters, allowing parameter metadata to be modified per instance and allowing parameter objects to be passed to Panel objects ([#306](https://github.com/holoviz/param/pull/306))
- Added label slot to Parameter, to allow overriding attribute name for display ([#319](https://github.com/holoviz/param/pull/319))
- Added step slot to Parameter, e.g. to control Panel widget step size ([#326](https://github.com/holoviz/param/pull/326))
- Added keywords_to_params utility for deducing Parameter types and ranges automatically ([#317](https://github.com/holoviz/param/pull/317))
- Added support for multiple outputs from a Parameterized ([#312](https://github.com/holoviz/param/pull/312))
- Added Selector as a more user-friendly version of ObjectSelector, accepting a list of options as a positional argument ([#316](https://github.com/holoviz/param/pull/316))
Changes affecting backwards compatibility:
- Changed from root logger to a param-specific logger; no change to API but will change format of error and warning messages ([#330](https://github.com/holoviz/param/pull/330))
- Old abstract class Selector renamed to SelectorBase; should be no change unless user code added custom classes inherited from Selector without providing a constructor ([#316](https://github.com/holoviz/param/pull/316))
Bugfixes and other improvements:
- Various bugfixes ([#320](https://github.com/holoviz/param/pull/320), [#323](https://github.com/holoviz/param/pull/323), [#327](https://github.com/holoviz/param/pull/327), [#329](https://github.com/holoviz/param/pull/329))
- Other improvements ([#315](https://github.com/holoviz/param/pull/315), [#325](https://github.com/holoviz/param/pull/325))
For more details, you can see a [full list of changes since the previous release](https://github.com/holoviz/param/compare/v1.8.2...v1.9.0).
## Version 1.8.2
Minor release:
- Added output decorator and outputs lookup method ([#299](https://github.com/holoviz/param/pull/299), [#312](https://github.com/holoviz/param/pull/312))
For more details, you can see a [full list of changes since the previous release](https://github.com/holoviz/param/compare/v1.8.2...v1.8.1).
## Version 1.8.1
Minor release:
- Added positional default arguments for nearly all Parameter subclasses (apart from ClassSelector)
- Minor bugfixes for watching callbacks
For more details, you can see a [full list of changes since the previous release](https://github.com/holoviz/param/compare/v1.8.1...v1.8.0).
## Version 1.8.0
Major new feature set: comprehensive support for events, watching, callbacks, and dependencies
- Parameterized methods can now declare `@depends(p,q)` to indicate that they depend on parameters `p` and `q` (defaulting to all parameters)
- Parameterized methods can depend on subobjects with `@depends(p.param,q.param.r)`, where `p.param` indicates dependencies on all parameters of `p` and `q.param.r` indicates a dependency on parameter `r` of `q`.
- Functions and methods can `watch` parameter values, re-running when those values change or when an explicit trigger is issued, and can unwatch them later if needed.
- Multiple events can be batched to trigger callbacks only once for a coordinated set of changes
Other new features:
- Added support in ObjectSelector for selecting lists and dicts ([#268](https://github.com/holoviz/param/pull/268))
- Added pandas DataFrame and Series parameter types ([#285](https://github.com/holoviz/param/pull/285))
- Added support for regular expression validation to String Parameter ([#241](https://github.com/holoviz/param/pull/241), [#245](https://github.com/holoviz/param/pull/245))
For more details, you can see a [full list of changes since the previous release](https://github.com/holoviz/param/compare/v1.8.0...v1.7.0).
## Version 1.7.0
Since the previous release (1.6.1), there should be no changes that affect existing code, only additions:
* A new param namespace object, which in future will allow subclasses of Parameterized to have much cleaner namespaces ([#230](https://github.com/holoviz/param/pull/230)).
* Started testing on python 3.7-dev ([#223](https://github.com/holoviz/param/pull/223)).
* param.version now provides functions to simplify dependants' setup.py/setup.cfg files (see https://github.com/holoviz-dev/autover/pull/49).
Although param should still work on python 3.3, we are no longer testing against it (unsupported by our test environment; [#234](https://github.com/holoviz/param/pull/234)).
For more details, you can see a [full list of changes since the previous release](https://github.com/holoviz/param/compare/v1.6.1...v1.7.0).
## Version 1.6.1
Restores support for the previous versioning system (pre 1.6; see [#225](https://github.com/holoviz/param/pull/225)), and fixes a number of issues with the new versioning system:
* Allow package name to differ from repository name (https://github.com/holoviz-dev/autover/pull/39)
* Allow develop install to work when repository is dirty (https://github.com/holoviz-dev/autover/pull/41)
* Fixed failure to report dirty when commit count is 0 (https://github.com/holoviz-dev/autover/pull/44)
## Version 1.6.0
Notable changes, fixes, and additions since the previous release (1.5.1) are listed below. You can also see a [full list of changes since the previous release](https://github.com/holoviz/param/compare/v1.5.1...v1.6.0).
Changes:
* `param.__version__` is now a string
* `param.version.Version` now supports a tag-based versioning workflow; if using the `Version` class, you will need to update your workflow (see [autover](https://github.com/holoviz-dev/autover) for more details).
* Dropped support for python 2.6 ([#175](https://github.com/holoviz/param/pull/175)).
* No longer attempt to cythonize param during installation via pip ([#166](https://github.com/holoviz/param/pull/166), [#194](https://github.com/holoviz/param/pull/194)).
Fixes:
* Allow `get_param_values()` to work on class ([#162](https://github.com/holoviz/param/pull/162)).
* Fixed incorrect default value for `param.Integer` ([#151](https://github.com/holoviz/param/pull/151)).
* Allow a `String` to be `None` if its default is `None` ([#104](https://github.com/holoviz/param/pull/104)).
* Fixed `ListSelector.compute_default()` ([#212](https://github.com/holoviz/param/pull/212)).
* Fixed checks for `None` in various `Parameter` subclasses ([#208](https://github.com/holoviz/param/pull/208)); fixes problems for subclasses of `Parameterized` that define a custom `__nonzero__` or `__len__`.
Additions:
* Added `DateRange` parameter.
Miscellaneous:
* No longer tested on python 3.2 (unsupported by our test environment; [#218](https://github.com/holoviz/param/pull/218)).
## Version 1.5.1
* Fixed error messages for ClassSelector with tuple of classes
* Added get and contains methods for ParamOverrides
A full list of changes since the previous release is available [here](https://github.com/holoviz/param/compare/v1.5.0...v1.5.1).
## Version 1.5.0
- Added Range, Color, and Date parameters
- Improved ObjectSelector error messages
- Minor bugfixes
A full list of changes since the previous release is available [here](https://github.com/holoviz/param/compare/v1.4.2...v1.5.0).
## Version 1.4.2
- Improved version reporting from version module
- Minor bugfixes
A full list of changes since the previous release is available [here](https://github.com/holoviz/param/compare/v1.4.1...v1.4.2).
## Version 1.4.1
* Selector parameters now respect order of options supplied
* Allowed softbounds to be accessed like an attribute
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.4.0...v1.4.1).
## Version 1.4.0 (2016/07)
* Added support for new [ParamNB](https://github.com/ioam/paramnb) project
* Added new parameter types Action, FileSelector, and ListSelector
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.3.2...v1.4.0).
## Version 1.3.2 (2015/04)
* Added Unicode support for param.String.
* Minor bugfixes.
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.3.1...v1.3.2).
## Version 1.3.1 (2015/03)
* Minor bugfix release to restore pre-1.3.0 script_repr behavior
(accidentally changed in 1.3.0) and to fix issues with logging.
* Param's logging interface now matches that of Python's logging
module, making it simpler to use logging (see Python's logging
module for details). Note therefore that Param's logging methods (a)
no longer call functions that are passed as arguments (instead,
Python's logging module does lazy string merges), and (b) no longer
automatically combine strings passed as arguments (instead, Python's
logging module supports string formatting).
* Improved set_param() method, now allowing multiple parameters to be
set easily via keyword arguments (as on initialization).
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.3.0...v1.3.1).
## Version 1.3.0 (2015/03)
* Added 'allow_None' support to all Parameters. Any subclass of
Parameter that checks types and/or values should be modified to add
appropriate handling of allow_None.
* Improved pretty printing (script_repr) of Parameterized instances,
and made available via the pprint method. The script_repr name will
be removed in a future release.
* Added (reproducible) time-dependent random streams
(numbergen.TimeAwareRandomState).
* Added label and unit parameters to param.Time class.
* Improved optional IPython extension.
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.2.1...v1.3.0).
## Version 1.2.1 (2014/06)
* Minor bugfix release to fix issues with version when param is
installed in a foreign git repository
* Made version module optional
* Improved ClassSelector and ParamOverrides
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.2.0...v1.2.1).
## Version 1.2.0 (2014/06)
* Added support for Python 3 (thanks to Marco Elver).
* Dropped support for Python 2.5.
* Added version module.
* Added optional numbergen package.
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.1.0...v1.2.0).
## Version 1.1.0 (2014/05)
* Switched to Python's own logging module.
* Improved support for time when using Dynamic parameters.
* Optional extension for IPython users.
A full list of changes since the previous release is available
[on GitHub](https://github.com/holoviz/param/compare/v1.0.0...v1.1.0).
## Version 1.0.0 (2012/07)
* First standalone release.
## Pre-1.0 (2003)
* Param was originally developed as part of [Topographica](http://ioam.github.io/topographica/), and has been in heavy usage as part of that project since 2003.
param-2.1.1/doc/roadmap.md 0000664 0000000 0000000 00000006225 14636363363 0015347 0 ustar 00root root 0000000 0000000 # Roadmap
Param is a mature library (originally from 2003) that changes very slowly and very rarely; it is fully ready for use in production applications. Major changes are undertaken only after significant discussions and with attention to how existing Param-based applications will be affected. Thus Param users should not expect only slow progress on these roadmap items, but they are listed here in the hopes that they will be useful.
Currently scheduled plans:
- Remove deprecated API and tag release 2.0. Deprecated API is noted in the source code and except in very rare cases has never been documented on the website, so removing these methods should only affect users of Param from 2020 or earlier.
- More powerful serialization (to JSON, YAML, and URLs) to make it simpler to persist the state of a Parameterized object. Some support already merged as https://github.com/holoviz/param/pull/414 , but still to be further developed as support for using Parameterized objects to build REST APIS (see https://github.com/holoviz/lumen for example usage).
Other items that are not yet scheduled but would be great to have:
- Integrate more fully with Python 3 language features like [type annotations](https://www.python.org/dev/peps/pep-0526) and [data classes](https://docs.python.org/3/library/dataclasses.html), e.g. to respect and validate against declared types without requiring an explicit `param.Parameter` declaration and potentially without inheriting from `param.Parameterized`, and to better support IDE type-checking features.
- Integrate and interoperate more fully with other frameworks like Django models, Traitlets, attrs, Django models, Pydantic, or swagger/OpenAPI, each of which capture or can use similar information about parameter names, values, and constraints and so in many cases can easily be converted from one to the other.
- Improve support for Param in editors, automatic formatting tools, linters, document generators, and other tools that process Python code and could be made to have special-purpose optimizations specifically for Parameterized objects.
- Follow PEP8 more strictly: PEP8 definitely wasn't written with Parameters in mind, and it typically results in badly formatted files when applied to Parameterized code. But PEP8 could be applied to Param's own code, e.g. using Black.
- Triaging open issues: The Param developer team consists of volunteers typically using Param on their projects but not explicity tasked with or funded to work on Param itself. It would thus be great if the more experienced Param users could help address some of the issues that have been raised but not yet solved.
- Improve test coverage
Other [issues](https://github.com/holoviz/param/issues) are collected on Github and will be addressed on various time scales as indicated by the issue's milestone (typically next minor release, next major release, or "wishlist" (not scheduled or assigned to any person but agreed to be desirable). Any contributor is encouraged to attempt to implement a "wishlist" item, though if it is particularly complex or time consuming it is useful to discuss it first with one of the core maintainers (e.g. by stating your intentions on the issue).
param-2.1.1/doc/upgrade_guide.md 0000664 0000000 0000000 00000041612 14636363363 0016527 0 ustar 00root root 0000000 0000000 # Upgrade guide
Welcome to the Upgrade Guide for Param! When we make backward-incompatible changes, we will provide a detailed guide here on how you can update your code to be compatible with the latest changes.
## Version 2.0
### Breaking changes
#### Parameter attributes inheritance
`Parameter`s have attributes like `default`, `doc`, `bounds`, etc. When redefining a `Parameter` in a subclass, attributes not specified in the subclass are meant to be inherited from the superclass.
Inheritance is not a new feature; it's a core design of Param. You can see in the example below that the `doc` attribute of the `x` Parameter on the class `B` has been inherited from `A`:
```python
class A(param.Parameterized):
x = param.Number(default=5, doc='The value of x')
class B(A):
x = param.Number(default=10)
print(B().param['x'].doc)
# The value of x
```
However, throughout the Param 1.x series, inheritance was broken in some subtle ways! The issues traced back to using `None` as the specific sentinel value for allowing inheritance, when `None` is also often a valid `Parameter` value. Let's have a look at two examples that have been fixed in Param 2.0.
In this first example we want to re-set the default value of `x` to `None` in a subclass. As you can see, the explicit `None` value we provided in `B` was discarded entirely in versions before Param 2.0, while the new version now correctly re-assigns the value to `None`:
```python
class A(param.Parameterized):
x = param.Number(default=5.0)
class B(A):
x = param.Number(default=None)
print(B().x)
# Param < 2: 5.0 :(
# Param 2.0: None :)
```
In this second example we want to narrow the bounds `x` in the subclass `B`. Because no default value is specified for `x` in `B`, you might reasonably have expected the default value of `5.0` to be inherited from `A`. However, prior to Param 2.0, instead the default value of the `Number` `Parameter` (`0.0`) is used for `B.x` instead of what was declared in `A`:
```python
class A(param.Parameterized):
x = param.Number(default=5.0, bounds=(-10, 10))
class B(A):
x = param.Number(bounds=(0, 10))
print(B().x)
# Param < 2: 0.0 :(
# Param 2.0: 5.0 :)
```
These are just two of the most common cases where inheritance changes can affect your code, but there are many other cases, affecting any attribute where `None` is a legal value. The new behavior should be much more predictable and intuitive, avoiding subtle cases where your code would previously have behaved inappropriately without necessarily having any obvious error. Fixing this was already enough to be worth the major bump to Param 2.0!
Because of all our work on making sure that Parameter attributes are properly inherited, we've realized that you can now more easily end up with a Parameter whose state, i.e. the combination of all of its attribute values, is invalid according to the Parameter declarations. Therefore, once class inheritance has completed as your classes get defined, we have added validation that the Parameter's *default* value is an allowed value. For now Param 2.0 is only emitting a warning when this validation fails, to avoid breaking your code on imports! If you do see these warnings, you should address them immediately by adding a legal default value or by relaxing one of the declared constraints on the value, because the warnings indicate a Parameter is in an invalid state. In the following example, the `bounds` of `x` are narrowed down in `B` without updating the `default` value that is inherited from `A.x` of `-1`, making the Parameter `x` on `B` in an invalid state:
```python
class A(param.Parameterized):
x = param.Number(default=-1, bounds=(-5, 5))
class B(A):
x = param.Number(bounds=(0, 5))
# Param < 2: No warning and B().x == 0.0
# Param 2.0: Warning and B().x == -1 / ParamFutureWarning: Number parameter 'B.x' failed to validate its default value on class creation, this is going to raise an error in the future. The Parameter is defined with attributes which when combined with attributes inherited from its parent classes (A) make it invalid. Please fix the Parameter attributes.
```
Param doesn't do any more validation that what was just explained when creating subclasses that override `Parameter`s. For instance, it doesn't programmatically enforce that a subclass should define a `Parameter` that is of the same type or a subtype of the `Parameter` defined in a super class. However, the best approach for you to follow is clearly to make sure that `Parameter`s defined in subclasses satisfy the ["is-a"](https://en.wikipedia.org/wiki/Is-a) relationship. I.e., for an instance `b` of subclass `B` and an instance `a` of parent class `A`, `b` should always be usable where `a` is. That's the general rule for inheritance, and for `Parameter`s it's specifically that any parameter value accepted by `B` should be a valid setting for `A`. That way any code written for `A`, including code that handles the various values of any attribute of `A`, can be trusted to work properly with any instance of `B`. In more concrete terms, it means a `Parameter` of a subclass should not increase the range of accepted values, it should instead narrow it down, i.e. by specifying a subtype (e.g. `param.Number` to `param.Integer`) or restricting the range of accepted values (e.g. smaller `bounds`).
#### Defining custom `Parameter`s
To implement `Parameter` attribute inheritance correctly as described above, we have had to make some changes to how new `Parameter` classes are declared. While the custom `Parameter`s you previously wrote for Param before 2.0 should continue to work as they always have, unless you update their definitions, they could continue to suffer from the attribute inheritance issues that have been fixed within Param itself. We now recommend custom `Parameter`s to be written following the pattern we have adopted internally. In particular, we have:
- introduced the `param.parameterized.Undefined` sentinel object that is used as the default value of the `Parameter` parameters in its `__init__()` method
- introduced the `_slot_defaults` class attribute to declare the actual default values of the `Parameter` parameters, e.g. in the example below the default value of `some_attribute` is declared to be `10`
- leveraged `@typing.overload` to expose the real default values to static type checkers and IDEs like VSCode
All put together, this is now how `Parameter`s are structured internally and how we recommend writing custom `Parameter` classes:
```python
class CustomParameter(Parameter):
__slots__ = ['some_attribute']
_slot_defaults = _dict_update(Parameter._slot_defaults,
default=None, some_attribute=10
)
@typing.overload
def __init__(
self,
default=None, *, some_attribute=10,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, *, some_attribute=Undefined, **params):
super().__init__(default=default, **params)
self.some_attribute = some_attribute
...
```
To make Parameter attributes work as expected, we have overridden `Parameter.__getattribute__` to detect whether the attribute value has been set to something that is not `Undefined`, and if not, to fall back to returning the default value declared in `_slot_defaults`:
```python
print(CustomParameter(some_attribute=0).some_attribute)
# 0
print(CustomParameter().some_attribute) # Fallback case
# 10
```
#### Default value of `name` accounted for
Every `Parameterized` class has always been equipped with a `name` `Parameter`, which was originally to support using a Parameterized object in a GUI context that needs a text label, but is not always needed in other contexts. At the class level the `name` value is the class name, equivalent to `.__name__`, and at the instance level the `name` value is automatically generated as a unique string, unless you set it in the constructor:
```python
class A(param.Parameterized):
x = param.Number()
print(A.name)
# A
print(A().name)
# A00002
print(A(name='some name').name)
# some name
```
However, sometimes you want to define your own default value for the `name` parameter, as in the following example. Before Param 2.0, any such default value was discarded at both the class and instance levels, but since 2.0 the provided `name` is now respected:
```python
class Person(param.Parameterized):
name = param.String(default='Eva')
print(Person.name)
# Param < 2: Person :(
# Param 2.0: Eva :)
print(Person().name)
# Param < 2: Person0000 :(
# Param 2.0: Eva :)
```
#### Setting a non-Parameter attribute via the constructor
Before Param 2.0, you could set an instance attribute that was not a `Parameter` via the constructor, though you would get a warning if you did so. This behavior was prone to let typos slip through your code, setting the wrong instance attribute but continuing to function. Starting from Param 2.0, providing an attribute value that is not a Parameter now raises a `TypeError`, similarly to when you call a Python callable with an incorrect parameter name:
```python
class A(param.Parameterized):
number = param.Number()
A(numbre=10) # oops typo!
# Param < 2: WARNING:param.A00002: Setting non-parameter attribute numbre=10 using a mechanism intended only for parameters
# Param 2.0: TypeError: A.__init__() got an unexpected keyword argument 'numbre'
```
#### `instance.param.watchers` value changed
`instance.param.watchers` no longer returns the transient watchers state, which was never very useful, and now instead returns what you would expect, i.e. a dictionary of the watchers set up on this instance. To access that dictionary previously, you would have had to access the private attribute `instance._param_watchers`, which is now deprecated and was never intended to be public API:
```python
class A(param.Parameterized):
x = param.Number()
@param.depends('x', watch=True)
def cb(self):
pass
print(A().param.watchers)
# Param < 2: []
# Param 2.0: {'x': {'value': [Watcher(...)]}}
```
#### Clean-up of the `Parameterized` namespace
To avoid having your Parameterized object namespaces polluted with internal Param details, the methods listed below have been removed from the `Parameterized` namespace (members available to any class that inherits from `param.Parameterized`). Most of the time, a replacement method is now available from the `.param` namespace instead:
- `_add_parameter`: use instead `param.add_parameter`
- `params`: use instead `.param.values()` or `.param['param']`
- `set_default`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `print_param_defaults`: `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `set_param`: use instead `.param.update`
- `set_dynamic_time_fn`: use instead `.param.set_dynamic_time_fn`
- `get_param_values`: use instead `.param.values().items()` (or `.param.values()` for the common case of `dict(....param.get_param_values())`)
- `force_new_dynamic_value`: use instead `.param.force_new_dynamic_value`
- `get_value_generator`: use instead `.param.get_value_generator`
- `inspect_value`: use instead `.param.inspect_value`
- `_set_name`: no replacement
- `__db_print`: no replacement
- `warning`: use instead `.param.warning`
- `message`: use instead `.param.log(param.MESSAGE, ...)`
- `verbose`: use instead `.param.log(param.VERBOSE, ...)`
- `debug`: use instead `.param.log(param.DEBUG, ...)`
- `print_param_values`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `defaults`: use instead `{k:v.default for k,v in p.param.objects().items()}`
- `pprint` and `_pprint`: use instead `.param.pprint`
- `script_repr`: use instead `param.parameterized.script_repr`
- `state_pop`: moved to `.param._state_pop`, it might be removed in a future version, let us know if you need it!
- `state_push`: moved to `.param._state_push`, it might be removed in a future version, let us know if you need it!
#### `Parameter` clean-up
- Removed unused `bounds` slot from `Boolean` and `Event`
- Removed private Parameter `_internal_name` slot
#### Additional removals
- Removed `Time.next` method that was only needed for Python 2
### Deprecations
Param 2.0 was originally meant to clean up even more Param's API, except that we noticed that deprecating API in the release notes of previous versions was not enough to warn Param's users (including ourselves!). Thus for 2.0 we decided to postpone removing some APIs, and this time properly warn Param's users that the code is about to be deleted. We've also spent a lot of time looking at the code base while working on this major release, and noticed additional clean up that could be made in the future. Therefore when you upgrade to 2.0, you are likely to encounter quite a large number of deprecation warnings. Make sure you're adapting your code as soon as you can whenever you notice one of the newly emitted warnings, because that code will not continue to be supported in later releases in the 2.x series. (Or you can pin your code to Param 1.x if you want to avoid the warnings and do not need any of the features or bugfixes from 2.0.)
Here is the complete list of deprecation warnings added in Param 2.0:
- Parameter signature:
- Instantiating parameters other than `default` with positional arguments is deprecated:
- `String('prefix-test', '^prefix')`: deprecated!
- `String('prefix-test', regex='^prefix')`: OK
- `String(default='prefix-test', regex='^prefix')`: OK
- For `Selector` parameters that accept `objects` as first positional argument, and `ClassSelector` parameters that accept `class_` as first positional argument, passing *any* argument by position is deprecated:
- `Selector([1, 2])`: deprecated!
- `Selector(objects=[1, 2])`: OK
- `ClassSelector((str, int))`: deprecated!
- `ClassSelector(class_=(str, int))`: OK
- It's possible that in the future the signature of these two parameters will be aligned with the other parameters to accept `default` as first and only positional argument, but for now please use an explicit keyword so that your code will be compatible with all versions.
- Parameter slots:
- `List._class`: use instead `item_type`.
- `Number.set_hook`: no replacement
- `param.__init__` module:
- `param.produce_value`: no replacement
- `param.as_unicode`: no replacement
- `param.is_ordered_dict`: no replacement
- `param.is_ordered_dict`: no replacement
- `param.hashable`: no replacement
- `param.named_objs`: no replacement
- `param.normalize_path`: no replacement
- `param.abbreviate_paths`: no replacement
- `param.parameterized` module:
- `param.parameterized.all_equal`: no replacement
- `param.parameterized.add_metaclass`: no replacement
- `param.parameterized.batch_watch`: use instead `batch_call_watchers`
- `param.parameterized.recursive_repr`: no replacement
- `param.parameterized.overridable_property`: no replacement
- Parameterized `.param` namespace; many of these methods have been deprecated since version 1.12.0, but because the deprecation was announced only in the release notes and not with runtime warnings, meany users have failed to realize the methods were deprecated, sometimes even us included! All these methods now emit deprecation warnings when executed and are now clearly marked as deprecated in the API reference:
- `.param.set_default`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `.param._add_parameter`: use instead `.param.add_parameter`
- `.param.params`: use instead `.param.values()` or `.param['param']`
- `.param.set_param`: use instead `.param.update`
- `.param.get_param_values`: use instead `.param.values().items()` (or `.param.values()` for the common case of `dict(....param.get_param_values())`)
- `.param.params_depended_on`: use instead `.param.method_dependencies`
- `.param.defaults`: use instead `{k:v.default for k,v in p.param.objects().items()}`
- `.param.print_param_defaults`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `.param.print_param_values`: use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
- `.param.message`: use instead `.param.log(param.MESSAGE, ...)`
- `.param.verbose`: use instead `.param.log(param.VERBOSE, ...)`
- `.param.debug`: use instead `.param.log(param.DEBUG, ...)`
- Some methods now (correctly) warn that they are not safe to run in a `Parameterized` subclass constructor until you have called `super().__init__(**params)`:
- `instance.param.objects(instance=True)`
- `instance.param.trigger("")`
- `instance.param.watch(callback, "")`
- Parameterized namespace:
- `instance._param_watchers` (getter and setter): use instead the property `inst.param.watchers`
param-2.1.1/doc/user_guide/ 0000775 0000000 0000000 00000000000 14636363363 0015530 5 ustar 00root root 0000000 0000000 param-2.1.1/doc/user_guide/Dependencies_and_Watchers.ipynb 0000664 0000000 0000000 00000112577 14636363363 0023660 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "33cd4c67",
"metadata": {},
"source": [
"# Dependencies and Watchers\n",
"\n",
"As outlined in the [Dynamic Parameters](Dynamic_Parameters.ipynb) guide, Param can be used in multiple ways, including as a static set of typed attributes, dynamic attributes that are computed when they are read (`param.Dynamic` parameters, a \"pull\" or \"get\" model), and using explicitly expressed chains of actions driven by events at the Parameter level (a \"push\" or \"set\" model described in this notebook). \n",
"\n",
"Unlike Dynamic Parameters, which calculate values when parameters are _accessed_, the dependency and watcher interface allows events to be triggered when parameters are _set_. With this interface, parameters and methods can declare that they should be updated or invoked when a given parameter is modified, spawning a cascading series of events that update settings to be consistent, adapt values as appropriate for a change, or invoke computations such as updating a displayed object when a value is modified. This approach is well suited to a GUI interface, where a user interacts with a single widget at a time but other widgets or displays need to be updated in response. The\n",
"[Dynamic Parameters](Dynamic_Parameters.ipynb) approach, in contrast, is well suited when Parameters update either on read or in response to a global clock or counter, such as in a simulation or machine-learning iteration.\n",
"\n",
"This user guide is structured as three main sections:\n",
"\n",
"- [Dependencies](#dependencies): High-level dependency declaration via the `@param.depends()` decorator\n",
"- [Watchers](#watchers): Low-level watching mechanism via `.param.watch()`.\n",
"- [Using dependencies and watchers](#using-dependencies-and-watchers): Utilities and tools for working with events created using either dependencies or watchers."
]
},
{
"cell_type": "markdown",
"id": "12e54858",
"metadata": {},
"source": [
"## Dependencies\n",
"\n",
"Param's `depends` decorator allows a programmer to express that a given computation \"depends\" on a certain set of parameters. For instance, if you have parameters whose values are interlinked, it's easy to express that relationship with `depends`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3001f2d9",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class C(param.Parameterized):\n",
" _countries = {'Africa': ['Ghana', 'Togo', 'South Africa'],\n",
" 'Asia' : ['China', 'Thailand', 'Japan', 'Singapore'],\n",
" 'Europe': ['Austria', 'Bulgaria', 'Greece', 'Switzerland']}\n",
" \n",
" continent = param.Selector(default='Asia', objects=list(_countries.keys()))\n",
" country = param.Selector(objects=_countries['Asia'])\n",
" \n",
" @param.depends('continent', watch=True)\n",
" def _update_countries(self):\n",
" countries = self._countries[self.continent]\n",
" self.param['country'].objects = countries\n",
" if self.country not in countries:\n",
" self.country = countries[0]\n",
"\n",
"c = C()\n",
"c.country, c.param.country.objects"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "93e1c6e6",
"metadata": {},
"outputs": [],
"source": [
"c.continent='Africa'\n",
"c.country, c.param.country.objects"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8258470a",
"metadata": {},
"outputs": [],
"source": [
"c"
]
},
{
"cell_type": "markdown",
"id": "e2f371c2",
"metadata": {},
"source": [
"As you can see, here Param updates the allowed and current values for `country` whenever someone changes the `continent` parameter. This code relies on the dependency mechanism to make sure these parameters are kept appropriately synchronized:\n",
"\n",
"1. First, we set up the default continent but do not declare the `default` for the `country` parameter. This is because this parameter is dependent on the `continent` and therefore it is easy to set up values that are inconsistent and makes it difficult to override the default continent since changes to both parameters need to be coordinated. \n",
"2. Next, if someone chooses a different continent, the list of countries allowed needs to be updated, so the method `_update_countries()` that (a) looks up the countries allowed for the current continent, (b) sets that list as the allowed objects for the `country` parameter, and (c) selects the first such country as the default country.\n",
"3. Finally, we expressed that the `_update_countries()` method depends on the `continent` parameter. We specified `watch=True` to direct Param to invoke this method immediately, whenever the value of `continent` changes. We'll see [examples of watch=False](#watch-false-dependencies) later. Importantly we also set `on_init=True`, which means that when instance is created the `self._update_countries()` method is automatically called setting up the `country` parameter appropriately. This avoids having to declare a `__init__` method to manually call the method ourselves and the potentially brittle process of setting up consistent defaults."
]
},
{
"cell_type": "markdown",
"id": "b14b37b6",
"metadata": {},
"source": [
"### Dependency specs\n",
"\n",
"The example above expressed a dependency of `_update_countries` on this object's `continent` parameter. A wide range of such dependency relationships can be specified:\n",
"\n",
"1. **Multiple dependencies**: Here we had only one parameter in the dependency list, but you can supply any number of dependencies (`@param.depends('continent', 'country', watch=True)`).\n",
"2. **Dependencies on nested parameters**: Parameters specified can either be on this class, or on nested Parameterized objects of this class. Parameters on this class are specified as the attribute name as a simple string (like `'continent'`). Nested parameters are specified as a dot-separated string (like `'handler.strategy.i'`, if this object has a parameter `handler`, whose value is an object `strategy`, which itself has a parameter `i`). If you want to depend on some arbitrary parameter elsewhere in Python, just create an `instantiate=False` (and typically read-only) parameter on this class to hold it, then here you can specify the path to it on _this_ object.\n",
"3. **Dependencies on metadata**: By default, dependencies are tied to a parameter's current value, but dependencies can also be on any of the declared metadata about the parameter (e.g. a method could depend on `country:constant`, triggering when someone changes whether that parameter is constant, or on `country:objects` (triggering when the objects list is replaced (not just changed in place as in appending). The available metadata is listed in the `__slots__` attribute of a Parameter object (e.g. \n",
"`p.param.continent.__slots__`). \n",
"4. **Dependencies on any nested param**: If you want to depend on _all_ the parameters of a nested object `n`, your method can depend on `'n.param'` (where parameter `n` has been set to a Parameterized object).\n",
"5. **Dependencies on a method name**: Often you will want to break up computation into multiple chunks, some of which are useful on their own and some which require other computations to have been done as prerequisites. In this case, your method can declare a dependency on another method (as a string name), which means that it will now watch everything that method watches, and will then get invoked after that method is invoked.\n",
"\n",
"We can see examples of all these dependency specifications in class `D` below:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6df85b16",
"metadata": {},
"outputs": [],
"source": [
"class D(param.Parameterized):\n",
" x = param.Number(7)\n",
" s = param.String(\"never\")\n",
" i = param.Integer(-5)\n",
" o = param.Selector(objects=['red', 'green', 'blue'])\n",
" n = param.ClassSelector(default=c, class_=param.Parameterized, instantiate=False) \n",
" \n",
" @param.depends('x', 's', 'n.country', 's:constant', watch=True)\n",
" def cb1(self):\n",
" print(f\"cb1 x={self.x} s={self.s} \"\n",
" f\"param.s.constant={self.param.s.constant} n.country={self.n.country}\")\n",
"\n",
" @param.depends('n.param', watch=True)\n",
" def cb2(self):\n",
" print(f\"cb2 n={self.n}\")\n",
"\n",
" @param.depends('x', 'i', watch=True)\n",
" def cb3(self):\n",
" print(f\"cb3 x={self.x} i={self.i}\")\n",
"\n",
" @param.depends('cb3', watch=True)\n",
" def cb4(self):\n",
" print(f\"cb4 x={self.x} i={self.i}\")\n",
"\n",
"d = D()\n",
"d"
]
},
{
"cell_type": "markdown",
"id": "80365d7f",
"metadata": {},
"source": [
"Here we have created an object `d` of type `D` with a unique ID like `D00003`. `d` has various parameters, including one nested Parameterized object in its parameter `n`. In this class, the nested parameter is set to our earlier object `c`, using `instantiate=False` to ensure that the value is precisely the same earlier object, not a copy of it. You can verify that it is the same object by comparing e.g. `name='C00002'` in the repr for the subobject in `d` to the name in the repr for `c` in the previous section; both should be e.g. `C00002`.\n",
"\n",
"Dependencies are stored declaratively so that they are accessible for other libraries to inspect and use. E.g. we can now examine the dependencies for the decorated callback method `cb1`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c13bd79d",
"metadata": {},
"outputs": [],
"source": [
"dependencies = d.param.method_dependencies('cb1')\n",
"[f\"{o.inst.name}.{o.pobj.name}:{o.what}\" for o in dependencies]"
]
},
{
"cell_type": "markdown",
"id": "7548280e",
"metadata": {},
"source": [
"Here we can see that method `cb1` will be invoked for any value changes in `d`'s parameters `x` or `s`, for any value changes in `c`'s parameter `country`, and a change in the `constant` slot of `s`. These dependency relationships correspond to the specification `@param.depends('x', 's', 'n.country', 's:constant', watch=True)` above.\n",
"\n",
"Now, if we change `x`, we can see that Param invokes `cb1`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "77caf9c1",
"metadata": {},
"outputs": [],
"source": [
"d.x = 5"
]
},
{
"cell_type": "markdown",
"id": "066453bf",
"metadata": {},
"source": [
"`cb3` and `cb4` are also invoked, because `cb3` depends on `x` as well, plus `cb4` depends on `cb3`, inheriting all of `cb3`'s dependencies.\n",
"\n",
"If we now change `c.country`, `cb1` will be invoked since `cb1` depends on `n.country`, and `n` is currently set to `c`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "17394110",
"metadata": {},
"outputs": [],
"source": [
"c.country = 'Togo'"
]
},
{
"cell_type": "markdown",
"id": "477ab1d1",
"metadata": {},
"source": [
"As you can see, `cb2` is also invoked, because `cb2` depends on _all_ parameters of the subobject in `n`. \n",
"\n",
"`continent` is also a parameter on `c`, so `cb2` will also be invoked if you change `c.continent`. Note that changing `c.continent` itself invokes `c._update_countries()`, so in that case `cb2` actually gets invoked _twice_ (once for each parameter changed on `c`), along with `cb1` (watching `n.country`):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "acc4c4cb",
"metadata": {},
"outputs": [],
"source": [
"c.continent = 'Europe'"
]
},
{
"cell_type": "markdown",
"id": "a973b325",
"metadata": {},
"source": [
"Changing metadata works just the same as changing values. Because `cb1` depends on the `constant` slot of `s`, it is invoked when that slot changes:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a6403a93",
"metadata": {},
"outputs": [],
"source": [
"d.param.s.constant = True"
]
},
{
"cell_type": "markdown",
"id": "68c82e25",
"metadata": {},
"source": [
"Importantly, if we replace a sub-object on which we have declared dependencies, Param automatically rebinds the dependencies to the new object:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f6195bdd",
"metadata": {},
"outputs": [],
"source": [
"d.n = C()"
]
},
{
"cell_type": "markdown",
"id": "af05eb1f",
"metadata": {},
"source": [
"Note that if the values of the dependencies on the old and new object are the same, no event is fired. \n",
"\n",
"Additionally the previously bound sub-object is now no longer connected:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9d52086e",
"metadata": {},
"outputs": [],
"source": [
"c.continent = 'Europe'"
]
},
{
"cell_type": "markdown",
"id": "6e4d5b80",
"metadata": {},
"source": [
"### `watch=False` dependencies\n",
"\n",
"The previous examples all supplied `watch=True`, indicating that Param itself should watch for changes in the dependency and invoke that method when a dependent parameter is set. If `watch=False` (the default), `@param.depends` declares that such a dependency exists, but does not automatically invoke it. `watch=False` is useful for setting up code for a separate library like [Panel](https://panel.holoviz.org) or [HoloViews](https://holoviews.org) to use, indicating which parameters the external library should watch so that it knows when to invoke the decorated method. Typically, you'll want to use `watch=False` when that external library needs to do something with the return value of the method (a functional approach), and use `watch=True` when the function is [side-effecty](https://en.wikipedia.org/wiki/Side_effect_(computer_science)), i.e. having an effect just from running it, and not normally returning a value.\n",
"\n",
"For instance, consider this Param class with methods that return values to display:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7f1ebe63",
"metadata": {},
"outputs": [],
"source": [
"class Mul(param.Parameterized):\n",
" a = param.Number(5, bounds=(-100, 100))\n",
" b = param.Number(-2, bounds=(-100, 100))\n",
"\n",
" @param.depends('a', 'b')\n",
" def view(self):\n",
" return str(self.a*self.b)\n",
"\n",
" def view2(self):\n",
" return str(self.a*self.b)\n",
"\n",
"prod = Mul(name='Multiplier')"
]
},
{
"cell_type": "markdown",
"id": "00ff51ea",
"metadata": {},
"source": [
"You could run this code manually:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "fc51ed2b",
"metadata": {},
"outputs": [],
"source": [
"prod.a = 7\n",
"prod.b = 10\n",
"prod.view()"
]
},
{
"cell_type": "markdown",
"id": "50ab0942",
"metadata": {},
"source": [
"Or you could pass the parameters and the `view` method to Panel, and let Panel invoke it as needed by following the dependency chain:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "05f1bb0d",
"metadata": {},
"outputs": [],
"source": [
"import panel as pn\n",
"pn.extension()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "050b268a",
"metadata": {},
"outputs": [],
"source": [
"pn.Row(prod.param, prod.view)"
]
},
{
"cell_type": "markdown",
"id": "acda7cc7",
"metadata": {},
"source": [
"Panel creates widgets for the parameters, runs the `view` method with the default values of those parameters, and displays the result. As long as you have a live Python process running (not just a static HTML export of this page as on param.holoviz.org), Panel will then watch for changes in those parameters due to the widgets and will re-execute the `view` method to update the output whenever one of those parameters changes. Using the dependency declarations, Panel is able to do all this without ever having to be told separately which parameters there are or what dependency relationships there are. \n",
"\n",
"How does that work? A library like Panel can simply ask Param what dependency relationships have been declared for the method passed to it:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3536291d",
"metadata": {},
"outputs": [],
"source": [
"[o.name for o in prod.param.method_dependencies('view')]"
]
},
{
"cell_type": "markdown",
"id": "899a41e8",
"metadata": {},
"source": [
"Note that in this particular case the `depends` decorator could have been omitted, because Param conservatively assumes that any method _could_ read the value of any parameter, and thus if it has no other declaration from the user, the dependencies are assumed to include _all_ parameters (including `name`, even though it is constant):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a8bef58c",
"metadata": {},
"outputs": [],
"source": [
"[o.name for o in prod.param.method_dependencies('view2')]"
]
},
{
"cell_type": "markdown",
"id": "f8383036",
"metadata": {},
"source": [
"Conversely, if you want to declare that a given method does not depend on any parameters at all, you can use `@param.depends()`. \n",
"\n",
"Be sure not to set `watch=True` for dependencies for any method you pass to an external library like Panel to handle, or else that method will get invoked _twice_, once by Param itself (discarding the output) and once by the external library (using the output). Typically you will want `watch=True` for a side-effecty function or method (typically not returning a value), and `watch=False` (the default) for a function or method with a return value, and you'll need an external library to do something with that return value."
]
},
{
"cell_type": "markdown",
"id": "1169f3b6",
"metadata": {},
"source": [
"### `@param.depends` with function objects\n",
"\n",
"The `depends` decorator can also be used with bare functions, in which case the specification should be an actual Parameter object, not a string. The function will be called with the parameter(s)'s value(s) as positional arguments:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "60a085b7",
"metadata": {},
"outputs": [],
"source": [
"@param.depends(c.param.country, d.param.i, watch=True)\n",
"def g(country, i):\n",
" print(f\"g country={country} i={i}\")\n",
"\n",
"c.country = 'Greece'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a7105a92",
"metadata": {},
"outputs": [],
"source": [
"d.i = 6"
]
},
{
"cell_type": "markdown",
"id": "cd198a2e",
"metadata": {},
"source": [
"Here you can see that in addition to the classmethods starting with `cb` previously set up to depend on the country, setting `c`'s `country` parameter or `d`'s `i` parameter now also invokes function `g`, passing in the current values of the parameters it depends on whenever the function gets invoked. `g` can then make a side effect happen such as updating any other data structure it can access that needs to be changed when `country` or `i` changes. \n",
"\n",
"Using `@param.depends(..., watch=False)` with a function allows providing bound standalone functions to an external library for display, just as in the `.view` method above.\n",
"\n",
"Of course, you can still invoke `g` with your own explicit arguments, which does not invoke any watching mechanisms:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c4e160c1",
"metadata": {},
"outputs": [],
"source": [
"g('USA', 7)"
]
},
{
"cell_type": "markdown",
"id": "00370f00",
"metadata": {},
"source": [
"## Watchers\n",
"\n",
"The `depends` decorator is built on Param's lower-level `.param.watch` interface, registering the decorated method or function as a `Watcher` object associated with those parameter(s). If you're building or using a complex library like Panel, you can use the low-level Parameter watching interface to set up arbitrary chains of watchers to respond to parameter value or metadata setting:\n",
"\n",
"- `obj.param.watch(fn, parameter_names, what='value', onlychanged=True, queued=False, precedence=0)`: Create and register a `Watcher` that will invoke the given callback `fn` when the `what` item (`value` or one of the Parameter's slots) is set (or more specifically, changed, if `onlychanged=True`). If `queued=True`, delays calling any events triggered during this callback's execution until all processing of the current events has been completed (breadth-first Event processing rather than the default depth-first processing). The `precedence` declares a precedence level for the Watcher that determines the priority with which the callback is executed. Lower precedence levels are executed earlier. Negative precedences are reserved for internal Watchers, i.e. those set up by `param.depends`. The `fn` will be invoked with one or more `Event` objects that have been triggered, as positional arguments. Returns a `Watcher` object, e.g. for use in `unwatch`.\n",
"\n",
"- `obj.param.watch_values(fn, parameter_names, what='value', onlychanged=True, queued=False, precedence=0)`: Easier-to-use version of `obj.param.watch` specific to watching for changes in parameter values. Same as `watch`, but hard-codes `what='value'` and invokes the callback `fn` using keyword arguments _param_name_=_new_value_ rather than with a positional-argument list of `Event` objects.\n",
"\n",
"- `obj.param.unwatch(watcher)`: Remove the given `Watcher` (typically obtained as the return value from `watch` or `watch_values`) from those registered on this `obj`.\n",
"\n",
"To see how to use `watch` and `watch_values`, let's make a class with parameters `a` and `b` and various watchers with corresponding callback methods:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9f076d1b",
"metadata": {},
"outputs": [],
"source": [
"def e(e):\n",
" return f\"(event: {e.name} changed from {e.old} to {e.new})\"\n",
"\n",
"class P(param.Parameterized):\n",
" a = param.Integer(default=0)\n",
" b = param.Integer(default=0)\n",
" \n",
" def __init__(self, **params):\n",
" super().__init__(**params)\n",
" self.param.watch(self.run_a1, ['a'], queued=True, precedence=2)\n",
" self.param.watch(self.run_a2, ['a'], precedence=1)\n",
" self.param.watch(self.run_b, ['b'])\n",
"\n",
" def run_a1(self, event):\n",
" self.b += 1\n",
" print('a1', self.a, e(event))\n",
"\n",
" def run_a2(self, event):\n",
" print('a2', self.a, e(event))\n",
"\n",
" def run_b(self, event):\n",
" print('b', self.b, e(event))\n",
" \n",
"p = P()\n",
"\n",
"p.a = 1"
]
},
{
"cell_type": "markdown",
"id": "6cdbd8e5",
"metadata": {},
"source": [
"Here, we have set up three Watchers, each invoking a method on `P` when either `a` or `b` changes. The first Watcher invokes `run_a1` when `a` changes, and in turn `run_a1` changes `b`. Since `queued=True` for `run_a1`, `run_b` is not invoked while `run_a1` executes, but only later once both `run_a1` and `run_a2` have completed (since both Watchers were triggered by the original event `p.a=1`).\n",
"\n",
"Additionally we have set a higher `precedence` value for `run_a1` which results in it being executed **after** `run_a2`.\n",
"\n",
"Here we're using data from the `Event` objects given to each callback to see what's changed; try `help(param.parameterized.Event)` for details of what is in these objects (and similarly try the help for `Watcher` (returned by `watch`) or `PInfo` (returned by `.param.method_dependencies`))."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cef96eae",
"metadata": {},
"outputs": [],
"source": [
"#help(param.parameterized.Event)\n",
"#help(param.parameterized.Watcher)\n",
"#help(param.parameterized.PInfo)"
]
},
{
"cell_type": "markdown",
"id": "c06d1a13",
"metadata": {},
"source": [
"## Using dependencies and watchers\n",
"\n",
"Whether you use the `watch` or the `depends` approach, Param will store a set of `Watcher` objects on each `Parameterized` object that let it manage and process `Event`s. Param provides various context managers, methods, and Parameters that help you work with Watchers and Events:\n",
"\n",
"- [`batch_call_watchers`](#batch-call-watchers): context manager accumulating and eliding multiple Events to be applied on exit from the context \n",
"- [`discard_events`](#discard-events): context manager silently discarding events generated while in the context\n",
"- [`.param.trigger`](#param-trigger): method to force creation of an Event for this Parameter's Watchers without a corresponding change to the Parameter\n",
"- [`.param.watchers`](#param-watchers): writable property to access the instance watchers\n",
"- [Event Parameter](#event-parameter): Special Parameter type providing triggerable transient Events (like a momentary push button)\n",
"- [Async executor](#async-executor): Support for asynchronous processing of Events, e.g. for interfacing to external servers\n",
"\n",
"Each of these will be described in the following sections."
]
},
{
"cell_type": "markdown",
"id": "9356f733",
"metadata": {},
"source": [
"### `batch_call_watchers`\n",
"\n",
"Context manager that accumulates parameter changes on the supplied object and dispatches them all at once when the context is exited, to allow multiple changes to a given parameter to be accumulated and short-circuited, rather than prompting serial changes from a batch of parameter setting:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "905456c3",
"metadata": {},
"outputs": [],
"source": [
"with param.parameterized.batch_call_watchers(p):\n",
" p.a = 2\n",
" p.a = 3\n",
" p.a = 1\n",
" p.a = 5"
]
},
{
"cell_type": "markdown",
"id": "9c25515a",
"metadata": {},
"source": [
"Here, even though `p.a` is changed four times, each of the watchers of `a` is executed only once, with the final value. One of those events then changes `b`, so `b`'s watcher is also executed once.\n",
"\n",
"If we set `b` explicitly, `b`'s watcher will be invoked twice, once for the explicit setting of `b`, and once because of the code `self.b += 1`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6c7fe2df",
"metadata": {},
"outputs": [],
"source": [
"with param.parameterized.batch_call_watchers(p):\n",
" p.a = 2\n",
" p.b = 8\n",
" p.a = 3\n",
" p.a = 1\n",
" p.a = 5"
]
},
{
"cell_type": "markdown",
"id": "1deb1709",
"metadata": {},
"source": [
"If all you need to do is set a batch of parameters, you can use `.update` instead of `batch_call_watchers`, which has the same underlying batching mechanism:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e511a92a",
"metadata": {},
"outputs": [],
"source": [
"p.param.update(a=9,b=2)"
]
},
{
"cell_type": "markdown",
"id": "acc97f01",
"metadata": {},
"source": [
"### `discard_events`\n",
"\n",
"Context manager that discards any events within its scope that are triggered on the supplied parameterized object. Useful for making silent changes to dependent parameters, e.g. in a setup phase. If your dependencies are meant to ensure consistency between parameters, be careful that your manual changes in this context don't put the object into an inconsistent state!"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cf129b7c",
"metadata": {},
"outputs": [],
"source": [
"with param.parameterized.discard_events(p):\n",
" p.a = 2\n",
" p.b = 9"
]
},
{
"cell_type": "markdown",
"id": "ffc9a462",
"metadata": {},
"source": [
"(Notice that none of the callbacks is invoked, despite all the Watchers on `p.a` and `p.b`.)"
]
},
{
"cell_type": "markdown",
"id": "67437fe6",
"metadata": {},
"source": [
"### `.param.trigger`\n",
"\n",
"Usually, a Watcher will be invoked only when a parameter is set (and only if it is changed, by default). What if you want to trigger a Watcher in other cases? For instance, if a parameter value is a mutable container like a list and you add or change an item in that container, Param's `set` method will never be invoked, because in Python the container itself is not changed when the contents are changed. In such cases, you can trigger a watcher explicitly, using `.param.trigger(*param_names)`. Triggering does not affect parameter values, apart from the special parameters of type Event (see [below](#Event-Parameter:)).\n",
"\n",
"For instance, if you set `p.b` to the value it already has, no callback will normally be invoked:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c2b06db2",
"metadata": {},
"outputs": [],
"source": [
"p.b = p.b"
]
},
{
"cell_type": "markdown",
"id": "9fb9a5a8",
"metadata": {},
"source": [
"But if you explicitly trigger parameter `b` on `p`, `run_b` will be invoked, even though the value of `b` is not changing:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b086d010",
"metadata": {},
"outputs": [],
"source": [
"p.param.trigger('b')"
]
},
{
"cell_type": "markdown",
"id": "621e183e",
"metadata": {},
"source": [
"If you trigger `a`, the usual series of chained events will be triggered, including changing `b`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "827ef750",
"metadata": {},
"outputs": [],
"source": [
"p.param.trigger('a')"
]
},
{
"cell_type": "markdown",
"id": "fc3cb5ba",
"metadata": {},
"source": [
"### `.param.watchers`\n",
"\n",
"For more advanced purposes it can be useful to inspect all the watchers set up on an instance, in which case you can use `inst.param.watchers` to obtain a dictionary with the following structure: `{parameter_name: {what: [Watcher(), ...], ...}, ...}`"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0b2ae598",
"metadata": {},
"outputs": [],
"source": [
"p.param.watchers"
]
},
{
"cell_type": "markdown",
"id": "42ffa0a0",
"metadata": {},
"source": [
"### `Event` Parameter\n",
"\n",
"An Event Parameter is a special Parameter type whose value is intimately linked to the triggering of events for Watchers to consume. Event has a Boolean value, which when set to `True` triggers the associated watchers (as any Parameter does) but then is automatically set back to `False`. \n",
"\n",
"Conversely, if events are triggered directly on a `param.Event` via `.trigger`, the value is transiently set to True (so that it's clear which of many parameters being watched may have changed), then restored to False when the triggering completes. An Event parameter is thus like a momentary switch or pushbutton with a transient True value that normally serves only to launch some other action (e.g. via a `param.depends` decorator or a watcher), rather than encapsulating the action itself as `param.Action` does. "
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8498624d",
"metadata": {},
"outputs": [],
"source": [
"class Q(param.Parameterized):\n",
" e = param.Event()\n",
" \n",
" @param.depends('e', watch=True)\n",
" def callback(self):\n",
" print(f'e=={self.e}')\n",
" \n",
"q = Q()\n",
"q.e = True"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "317b053e",
"metadata": {},
"outputs": [],
"source": [
"q.e"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b423aa8b",
"metadata": {},
"outputs": [],
"source": [
"q.param.trigger('e')"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "bb5b83ae",
"metadata": {},
"outputs": [],
"source": [
"q.e"
]
},
{
"cell_type": "markdown",
"id": "8f17a138",
"metadata": {},
"source": [
"### Async executor\n",
"\n",
"Param's events and callbacks described above are all synchronous, happening in a clearly defined order where the processing of each function blocks all other processing until it is completed. Watchers can also be used with the Python3 asyncio [`async`/`await`](https://docs.python.org/3/library/asyncio-task.html) support to operate asynchronously. The asynchronous executor can be defined on `param.parameterized.async_executor` by default it will start an [asyncio](https://docs.python.org/3/library/asyncio.html) event loop or reuse the one that is running. This allows you to use coroutines and other asynchronous functions as `.param.watch` callbacks.\n",
"\n",
"As an example we can watch results accumulate:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "03ece21a",
"metadata": {},
"outputs": [],
"source": [
"import param, asyncio, aiohttp\n",
"\n",
"class Downloader(param.Parameterized):\n",
" url = param.String()\n",
" results = param.List()\n",
" \n",
" def __init__(self, **params):\n",
" super().__init__(**params)\n",
" self.param.watch(self.fetch, ['url'])\n",
"\n",
" async def fetch(self, event):\n",
" async with aiohttp.ClientSession() as session:\n",
" async with session.get(event.new) as response:\n",
" img = await response.read()\n",
" self.results.append((event.new, img))\n",
"\n",
"f = Downloader()\n",
"n = 7\n",
"for index in range(n):\n",
" f.url = f\"https://picsum.photos/800/300?image={index}\"\n",
"\n",
"f.results"
]
},
{
"cell_type": "markdown",
"id": "4744d8c7",
"metadata": {},
"source": [
"When you execute the above cell, you will normally get `[]`, indicating that there are not yet any results available. \n",
"\n",
"What the code does is to request 7 different images from an image site by repeatedly setting the `url` parameter of `Downloader` to a new URL. Each time the `url` parameter is modified, because of the `self.param.watch` call, the `self.fetch` callback is invoked. Because it is marked `async` and uses `await` internally, the method call returns without waiting for results to be available. Once the `await`ed results are available, the method continues with its execution and a tuple (_image_name_, _image_data_) is added to the `results` parameter.\n",
"\n",
"If you need to have all the results available (and have an internet connection!), you can wait for them:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "38da7bb2",
"metadata": {},
"outputs": [],
"source": [
"print(\"Waiting: \", end=\"\")\n",
"while len(f.results) 10).rx.where('Risk of flooding', 'Everything is normal')"
]
},
{
"cell_type": "markdown",
"id": "e1e80a15-e715-4cb7-bde8-17005e64c78d",
"metadata": {},
"source": [
"The same thing can also easily be achieved by using parameter binding:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "13f3bc65-be27-451e-b119-3faf0df6c559",
"metadata": {},
"outputs": [],
"source": [
"param.bind(lambda value: 'Risk of flooding' if value > 10 else 'Everything is normal', corrected).rx()"
]
},
{
"cell_type": "markdown",
"id": "d1099127-bc12-4068-a123-737fbc7aae66",
"metadata": {},
"source": [
"## Classes"
]
},
{
"cell_type": "markdown",
"id": "c5cff863-cbf3-4e44-a1da-df915a9deab7",
"metadata": {},
"source": [
"In the context of a class we can depend on a parameter that is driven by a generator as normal:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "137954a7-9c9d-474c-92b8-fdf2b9a29c03",
"metadata": {},
"outputs": [],
"source": [
"class TidalWarning(TidalGauge):\n",
"\n",
" message = param.String()\n",
" \n",
" @param.depends('height', watch=True)\n",
" def _update_message(self):\n",
" self.message = 'Risk of flooding' if self.height > 10 else 'Everything is normal'\n",
"\n",
"warn = TidalWarning(height=poll_sensor)\n",
"\n",
"warn.param['message'].rx()"
]
},
{
"cell_type": "markdown",
"id": "154d60b8-6460-4f83-9d12-9dc7bab45625",
"metadata": {},
"source": [
"## Asynchronous Generators\n",
"\n",
"Generators are powerful and internally Param will execute the generators on a separate thread to ensure that it does not block the main event loop. However, often an asynchronous generator is more appropriate since many operations that rely on generators are waiting on some external event, i.e. by polling a file or network resource, which can be done asynchronously.\n",
"\n",
"Regular generators and asynchronous generators can be used interchangeably:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6fe71ab8-c87e-4e30-914e-d043f7922766",
"metadata": {},
"outputs": [],
"source": [
"import asyncio\n",
"\n",
"async def poll_sensor_async(timeout=0.5):\n",
" while True:\n",
" yield tidal_gauge()\n",
" await asyncio.sleep(timeout)\n",
"\n",
"async_gauge = TidalGauge(height=poll_sensor_async)\n",
"\n",
"async_gauge.param.height.rx()"
]
},
{
"cell_type": "markdown",
"id": "fde666d8-38a8-4829-ad25-81a039f09055",
"metadata": {},
"source": [
"## Dependencies\n",
"\n",
"Now let us say that our generator itself has some dependency, e.g. we want to be able to control the sampling frequency of our gauge. To achieve this we can bind a parameter to our generator:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f50d6bc7-7ec6-40fc-a4fa-71db0ae8e413",
"metadata": {},
"outputs": [],
"source": [
"class VariableRateTidalGauge(TidalGauge):\n",
"\n",
" frequency = param.Integer(default=2, doc=\"\"\"\n",
" Frequency in Hz to sample the tidal gauge sensor at.\"\"\")\n",
"\n",
"variable_gauge = VariableRateTidalGauge(frequency=5)\n",
"\n",
"variable_gauge.height = param.bind(poll_sensor_async, timeout=1/variable_gauge.param.frequency.rx())\n",
"\n",
"variable_gauge.param.height.rx()"
]
},
{
"cell_type": "markdown",
"id": "eb210a56-2b9b-4804-8080-f856eb38234f",
"metadata": {},
"source": [
"Now we can vary the frequency at which our generator samples the sensor:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "14e0cfea-ad5a-4399-89ff-4bdfad0b25ed",
"metadata": {},
"outputs": [],
"source": [
"variable_gauge.frequency = 1"
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/How_Param_Works.ipynb 0000664 0000000 0000000 00000037033 14636363363 0021643 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "8c73a0b0",
"metadata": {},
"source": [
"# How Param Works\n",
"\n",
"Param seamlessly makes Python attributes have a much richer set of behaviors than they would otherwise, at once both more powerful (with automatic dynamic behavior) and more tightly controlled by the class author. It is natural to wonder how Param achieves this, especially given that it is a normal pure-Python library, not an alternative implementation of Python or a pre-processor. The answer is that Param makes extensive use of Python language features that allow tailoring the behavior of attribute getting and setting in sophisticated ways. You don't need to read any of the material on this page to use Param successfully, but it might help you understand what's going on \"under the hood\" for debugging or optimizing complex situations or for extending Param.\n",
"\n",
"## Descriptors\n",
"\n",
"A `Parameter` object is a type of Python \"descriptor\", i.e., an object that implements custom `__get__` and/or `__set__` behavior. When a descriptor is an attribute of a class, Python will invoke those custom methods instead of simply getting and setting the actual value of the attribute (i.e., the `Parameter` object). The [Python descriptor docs](https://docs.python.org/3/howto/descriptor.html) explain this process in detail, but briefly, let's consider a simple descriptor that returns how many times it has been accessed:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "af0cddab",
"metadata": {},
"outputs": [],
"source": [
"class Count:\n",
" def __init__(self, start=0):\n",
" self._count = start\n",
" \n",
" def __get__(self, obj, objtype=None):\n",
" self._count += 1\n",
" return self._count"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1488fb8c",
"metadata": {},
"outputs": [],
"source": [
"class C:\n",
" x = 5\n",
" y = Count(0)\n",
"\n",
"c = C()\n",
"\n",
"c.x, c.x, c.x, c.y, c.y, c.y"
]
},
{
"cell_type": "markdown",
"id": "4876a7f6",
"metadata": {},
"source": [
"As you can see, class attributes `x` and `y` here can both be used the same way, but `x` is a normal Python attribute, returning the fixed value `5` that was set on the class, while `y` is a descriptor and returns a computed value when accessed (rather than returning itself as you might think from the syntax), and thus gives a different value each time. Parameters are much more complex than the above example, but this descriptor support provides the underlying mechanism for having full-featured attribute behavior like dynamic values, bounds checking, and so on."
]
},
{
"cell_type": "markdown",
"id": "8d07cbda",
"metadata": {},
"source": [
"## Slots\n",
"\n",
"As described in the [Parameters docs](Parameters.ipynb), Parameters can store a rich collection of metadata about each parameter. Storing a full object and associated dictionary of metadata for each class and instance attribute could get expensive (i.e., slow and using a lot of memory), so Parameters are implemented using [slots](https://docs.python.org/3/reference/datamodel.html#slots). A slot is like a normal Python attribute, but instead of being stored in the convenient and flexible but slow `__dict__` attribute of the object, slots are stored in a fixed-size data structure `__slots__` that works like a C `struct`. `__slots__` reserves just enough space to store these attributes, which can be accessed instantaneously rather than requiring a dictionary lookup (hash table search).\n",
"\n",
"Using `__slots__` requires special support for operations to copy and restore Parameters (e.g. for Python persistent storage pickling); see `__getstate__` and `__setstate__`. A Parameter defines at least these slots, with additional slots added for each subclass:\n",
"\n",
"```\n",
"__slots__ = ['name', 'default', 'doc',\n",
" 'precedence', 'instantiate', 'constant', 'readonly',\n",
" 'pickle_default_value', 'allow_None', 'per_instance',\n",
" 'watchers', 'owner', 'allow_refs', 'nested_refs', '_label']\n",
"```\n",
"\n",
"In most cases, you can just treat a Parameter's existing slots like attributes of the Parameter class; they work just the same as regular attributes except for speed and storage space. However, if you add a _new_ attribute to a Parameter class, you have to make sure that you also add it to the `__slots__` defined for that Parameter class, or you'll either get an error or else the Parameter will get an unnecessary full `__dict__` object just to hold the one new attribute. "
]
},
{
"cell_type": "markdown",
"id": "cac0fda5",
"metadata": {},
"source": [
"## Metaclasses\n",
"\n",
"Another way `Parameter` and `Parameterized` differ from ordinary Python classes is that they specify a special [metaclass](https://docs.python.org/3/reference/datamodel.html#metaclasses) that determines how they behave. Just like you instantiate a Python class to get a Python object, you instantiate a Python metaclass to get a Python class. Most classes are instances of the default metaclass named `type`, but with a custom metaclass, you can define how every Python class with that metaclass will behave, at a fundamental level. \n",
"\n",
"The `ParameterMetaclass` is fairly simple, mainly overriding docstrings so that `help(someparam)` gives the declared documentation for the Parameter instance, rather than the less-useful docstring for the underlying class that it would otherwise display. This behavior is convenient, but not essential to the operation of Param. \n",
"\n",
"`ParameterizedMetaclass`, on the other hand, defines a lot of the behavior behind Param's features. In particular, the metaclass implements the behavior for getting and setting parameter values at the class level, similar to how a descriptor controls such behavior at the instance level. Without the metaclass, setting the value of a class attribute to a scalar like `5` would wipe out the `Parameter` object rather than updating the default value. The metaclass thus performs the same role at the class level as descriptors do at the instance level. Descriptors allow setting the value of an instance attribute without overriding the `Parameter` object on that instance, and the metaclass allows setting the value of a class attribute without overridding the `Parameter` object on the class. All told, the ParameterizedMetaclass handles: \n",
"\n",
"- allowing Parameter default values to be set at the class level (as just described),\n",
"- supporting inheriting Parameter objects from superclasses, \n",
"- instantiating parameter default values (if needed)\n",
"- populating the `name` slot of each Parameter by its attribute name in the class,\n",
"- reporting whether a class has been declared to be abstract (useful for ignoring it in selectors),\n",
"- various bookkeeping about dependencies and watchers, \n",
"- generating docstrings at the class level for each Parameter in the class so that `help(parameterizedclass)` displays not just the class docstring but also information about the Parameters in it (or in superclasses)\n",
"\n",
"Thus much of how Param works depends on ParameterizedMetaclass. "
]
},
{
"cell_type": "markdown",
"id": "60341a22",
"metadata": {},
"source": [
"## Custom attribute access\n",
"\n",
"The above mechanisms let Param [customize attribute access](https://docs.python.org/3/reference/datamodel.html#customizing-attribute-access) for dynamic behavior and control over user settings. As an example of how this all fits together, consider the following code:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4d6e587e",
"metadata": {},
"outputs": [],
"source": [
"from param import Parameterized, Parameter\n",
"\n",
"class A(Parameterized):\n",
" p = Parameter(default=1, per_instance=False, instantiate=False)\n",
"\n",
"a1 = A()\n",
"a2 = A()"
]
},
{
"cell_type": "markdown",
"id": "c03ebf19",
"metadata": {},
"source": [
"Here, a1 and a2 share one Parameter object (`A.__dict__['p']`), because `per_instance` is `False`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6eb529a8",
"metadata": {},
"outputs": [],
"source": [
"A.__dict__['p'] is a1.param.p is a2.param.p"
]
},
{
"cell_type": "markdown",
"id": "03b20d6f",
"metadata": {},
"source": [
"The default (class-attribute) value of p is stored in this Parameter object (`A.__dict__['p'].default`), but is accessible as `A.p` due to the Parameter being a descriptor:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0fe38b09",
"metadata": {},
"outputs": [],
"source": [
"A.__dict__['p'].default"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "886bc3d5",
"metadata": {},
"outputs": [],
"source": [
"A.p"
]
},
{
"cell_type": "markdown",
"id": "36ef8c10",
"metadata": {},
"source": [
"If the value of `p` is set on `a1`, `a1`'s value of `p` is stored in the `a1` instance itself, in a dictionary named `values` under the private namespace `_param__private`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "90061161",
"metadata": {},
"outputs": [],
"source": [
"a1.p = 2\n",
"a1._param__private.values['p']"
]
},
{
"cell_type": "markdown",
"id": "9b5c6a79",
"metadata": {},
"source": [
"When `a1.p` is requested, `a1._param__private.values['p']` is returned. When `a2.p` is requested, `p` is not found in `a2._param__private.values`, so `A.__dict__['p'].default` (i.e. `A.p`) is returned instead:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ec1ac4fc",
"metadata": {},
"outputs": [],
"source": [
"a2.p"
]
},
{
"cell_type": "markdown",
"id": "82208f0d",
"metadata": {},
"source": [
"Because the value for `a2.p` is returned from `A.p`, changing `A.p` will affect `a2.p`, but not `a1.p` since it has its own independent value:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3f1d08b5",
"metadata": {},
"outputs": [],
"source": [
"A.p = 3\n",
"a2.p, a1.p"
]
},
{
"cell_type": "markdown",
"id": "88a854b5",
"metadata": {},
"source": [
"If `p` was not defined in `A` but was defined in a superclass, the value found in that superclass would be returned instead. \n",
"\n",
"You can re-execute the above code changing to `per_instance=True` and/or `instantiate=True` on Parameter `p` and see how the behavior differs. With `per_instance=True` (which would normally be the default), `a1` and `a2` would each have independent copies of the `Parameter` object, and with `instantiate=True`, each instance would get its own copy of the class's default value, making it immune to later changes at the class level."
]
},
{
"cell_type": "markdown",
"id": "b86f55e3-5ae5-4879-9b4c-273e859b6fec",
"metadata": {},
"source": [
"## References\n",
"\n",
"Beyond the custom attribute access mechanisms of a single `Parameter`, Param can link together multiple Parameters. With the `allow_refs` option, a `Parameter` can act as a dynamic reference to another `Parameter`. This enables the values of two or more Parameters to stay in sync. Any change to the referenced Parameter's value is automatically reflected in all Parameters that reference it."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "fba9fbdc-0776-4cd3-8250-e00487593d57",
"metadata": {},
"outputs": [],
"source": [
"class B(Parameterized):\n",
" \n",
" p = Parameter(default=1, allow_refs=True)"
]
},
{
"cell_type": "markdown",
"id": "27beb80b-415f-41cb-b909-adb6822e7e9a",
"metadata": {},
"source": [
"Having declared a `Parameter` that allows references we can now pass the parameter `p` of `b1` to parameter `p` of `b2`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "22a51c29-c286-4e0f-b1a6-1e02bc4149da",
"metadata": {},
"outputs": [],
"source": [
"b1 = B(p=14)\n",
"b2 = B(p=b1.param.p)"
]
},
{
"cell_type": "markdown",
"id": "5eab5e13-66df-4001-8d70-2cab70449641",
"metadata": {},
"source": [
"Inspecting `b2.p` we will see that `p` of `b2` now reflects the value of `b1.p`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "fdc58565-f327-405f-958d-b49caa70adb3",
"metadata": {},
"outputs": [],
"source": [
"b2.p"
]
},
{
"cell_type": "markdown",
"id": "7322e310-9105-48c9-a0b8-41cb80bcf4e6",
"metadata": {},
"source": [
"Even when we update the value of `b1.p` the value of `b2.p` will reflect the change:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "961aebc0-45b5-458d-919c-1ba6a3c286e7",
"metadata": {},
"outputs": [],
"source": [
"b1.p = 7\n",
"\n",
"b2.p"
]
},
{
"cell_type": "markdown",
"id": "75c5eb72-3132-458c-9b30-b5cd1e64b63d",
"metadata": {},
"source": [
"Internally Param will [watch](Dependencies_and_Watchers.ipynb#watchers) all Parameters associated with the reference by calling `param.parameterized.resolve_ref` and then use `param.parameterized.resolve_value` to resolve the current value of the reference.\n",
"\n",
"If we explicitly set `b2.p` however the two values will become unsynced, i.e. the Watcher created when setting the reference will be removed:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2e02cb21-a4ab-48fb-a516-da17feaf0da0",
"metadata": {},
"outputs": [],
"source": [
"b2.p = 3\n",
"\n",
"print(b1.p, b2.p)"
]
},
{
"cell_type": "markdown",
"id": "701e26c3-6eb0-4c76-b453-cc37be06ac41",
"metadata": {},
"source": [
"and any subsequent changes to `b1.p` will not be reflected by `b2`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "50aedbea-7902-4f1a-8e98-6866a965eda8",
"metadata": {},
"outputs": [],
"source": [
"b1.p = 27\n",
"\n",
"b2.p"
]
},
{
"cell_type": "markdown",
"id": "07d982cd-c0f1-496f-8086-28a882266901",
"metadata": {},
"source": [
"If a new reference is assigned then the old `Watcher`(s) will be removed and if the new value also represents a reference new `Watcher`(s) will be registered."
]
},
{
"cell_type": "markdown",
"id": "c3e3d3aa",
"metadata": {},
"source": [
"# Other notes\n",
"\n",
"Once we have Parameter descriptors and the metaclasses, there is relatively little left for the Parameterized class itself to do:\n",
"\n",
"- implementing the rest of [dependencies and watchers](Dependencies_and_Watchers.ipynb)\n",
"- providing a constructor that lets you set instance parameters\n",
"- instantiating and providing the `.param` accessor for invoking methods and accessing the Parameter objects\n",
"- handling state saving and restoring (pickling)\n",
"\n",
"And that's it for the core of Param! There are other behaviors implemented at the level of specific Parameters, but those are typically localized and can be understood by reading the class docstring for that Parameter type."
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/Logging_and_Warnings.ipynb 0000664 0000000 0000000 00000022440 14636363363 0022655 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "7627a6fe",
"metadata": {},
"source": [
"# Logging and Warnings\n",
"\n",
"`Parameterized` objects provide methods for displaying logging messages and warnings in a way that can be controlled and redirected globally using the standard Python [logging](https://docs.python.org/3/library/logging.html) module (see the [logging cookbook](https://docs.python.org/3/howto/logging.html)). Compared to using a Python logger directly, using these methods inside your Parameterized class helps users by making the messages consistent, each prepending with information about the Parameterized object where the call was made so that your users can understand what the message indicates.\n",
"\n",
"By default, a Python logger named `param` will be instantiated to do the logging, but another logger can be supplied by setting `param.parameterized.logger` to it after importing `param.parameterized`.\n",
"\n",
"\n",
"## Writing log messages\n",
"\n",
"Each logging message has an associated logging `level` that indicates how severe a condition is being described (DEBUG, VERBOSE, INFO (aka \"message\"), WARNING, ERROR, or CRITICAL). These levels are as defined by the logging module, except for the addition of VERBOSE as a level intermediate between DEBUG (internal debugging information) and INFO (user-relevant non-error messages).\n",
"\n",
"The typical way to print a message is to call `.param.log()` with one of the following logging levels:\n",
"\n",
"- `.param.log(param.DEBUG, ...)`: Detailed debugging information, not displayed onscreen by default.\n",
"- `.param.log(param.VERBOSE, ...)`: Additional sometimes-useful information, not displayed onscreen by default.\n",
"- `.param.log(param.INFO, ...)`: Informative message, displayed onscreen by default.\n",
"- `.param.log(param.WARNING, ...)`: Warning of an unexpected or inappropriate but non-fatal condition, displayed onscreen by default.\n",
"\n",
"For convenience and to allow eventual integration with the Python [warnings](https://docs.python.org/3/library/warnings.html) module, `.param.warning(` is available as an alias for `.param.log(param.WARNING,`:\n",
"\n",
"- `.param.warning(...)`: Warning of an unexpected or inappropriate but non-fatal condition, displayed onscreen by default.\n",
"\n",
"The arguments accepted in each case are the same as those of [logging.debug()](https://docs.python.org/3/library/logging.html#logging.debug). Specifically, each call is like `.param.debug(msg, *args, **kw)`, where `msg` is an [old-style ('%') format string](https://wiki.python.org/moin/StringFormatting) and the `args` and `kwargs` will be merged with that format string. E.g.:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1daef0ad",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"desired = 1\n",
"actual = 5\n",
"\n",
"param.main.param.log(param.INFO, \"Welcome!\")\n",
"param.main.param.log(param.VERBOSE, \"Local variables: %s\", locals())\n",
"param.main.param.log(param.WARNING, \"Value %02d is not %d\", actual, desired)\n",
"param.main.param.warning(\"Value %02d is not %d\", actual, desired)"
]
},
{
"cell_type": "markdown",
"id": "ff2462c4",
"metadata": {},
"source": [
"Here we've used the default global Parameterized object `param.main`, useful for generic module-level messages, but more often you would make a call like `self.param.log()` _inside_ a Parameterized class instead. You can see that the messages are each prefixed by the logging level, `param` (the name of the default logger), and the name of this object (`main` in this case). You can also see that, by default, verbose messages are not actually printed.\n",
"\n",
"You may wonder (a) why the formatting string is \"old style\" , and (b) why the formatting values \"actual, desired\" are not combined directly with the formatting string. I.e., why not just use a Python3 f-string, like:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9f3b2a86",
"metadata": {},
"outputs": [],
"source": [
"param.main.param.log(param.WARNING, f\"Value {actual:02} is not {desired}\") # Discouraged!"
]
},
{
"cell_type": "markdown",
"id": "4a96c56b",
"metadata": {},
"source": [
"The answer is that particularly for `debug` and `verbose` messages that could occur inside frequently executed code, we want logging to be \"lazy\", in that we do not want to render a string representation for `actual`, `desired`, etc. unless we are actually printing the message. If we use an f-string or any other locally formatted string, the string formatting will be done _whether_ _or_ _not_ the message will be displayed, potentially causing drastic slowdowns in your code. For instance, in the code above, the entire `locals()` dictionary would be iterated over, printed to strings. Of course, since the message isn't being printed in that case, the entire format string would then be discarded, greatly slowing down the code without producing any output. To avoid that, the logging module has to defer the string substitution and handle that itself, and it was written before Python3, so it only supports old-style substitution. So, even though it is more awkward, it is highly recommended to use this old-style, lazy string formatting support."
]
},
{
"cell_type": "markdown",
"id": "aeeda03b",
"metadata": {},
"source": [
"## Controlling the logging level\n",
"\n",
"You can use the `param.parameterized.logging_level` context manager to temporarily reduce or elevate the logging level while you execute code:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f09f288a",
"metadata": {},
"outputs": [],
"source": [
"with param.logging_level('CRITICAL'):\n",
" param.main.param.log(param.INFO, \"Message 1\")\n",
" param.main.param.log(param.VERBOSE, \"Verbose 1\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "85dbe122",
"metadata": {},
"outputs": [],
"source": [
"with param.logging_level('DEBUG'):\n",
" param.main.param.log(param.INFO, \"Message 2\")\n",
" param.main.param.log(param.VERBOSE, \"Verbose 2\")"
]
},
{
"cell_type": "markdown",
"id": "3b881898",
"metadata": {},
"source": [
"You can also set the value more globally (and permanently) on the logger object:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a429ac57",
"metadata": {},
"outputs": [],
"source": [
"param.get_logger().setLevel(param.DEBUG)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7afeb934",
"metadata": {},
"outputs": [],
"source": [
"param.main.param.log(param.INFO, \"Message 2\")\n",
"param.main.param.log(param.VERBOSE, \"Verbose 2\")"
]
},
{
"cell_type": "markdown",
"id": "4ebe358c",
"metadata": {},
"source": [
"For testing, continuous integration (CI), or other specific applications, you can also set `param.parameterized.warnings_as_exceptions = True`, which will cause your program to raise an exception the first time it encounters any warning."
]
},
{
"cell_type": "markdown",
"id": "54f42ad0",
"metadata": {},
"source": [
"# Controlling the formatting of log messages\n",
"\n",
"The Python logging module provides many options for configuring how the log messages are generated. For complete control, you can instantiate your own logger and set `param.parameterized.logger` to it after importing `param.parameterized`.\n",
"\n",
"A hook is provided for the relatively common case when you want to prefix each message with the time of day, a progress indication, a simulator time, or some other indication of a global state. Specifically, you can set `param.parameterized.dbprint_prefix` to a callable object returning a string. The object will be called when constructing each message:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "be2a5f2c",
"metadata": {},
"outputs": [],
"source": [
"from datetime import datetime\n",
"#param.parameterized.warnings_as_exceptions = True\n",
"\n",
"param.parameterized.dbprint_prefix=lambda: str(datetime.now())\n",
"\n",
"param.main.param.warning(\"Message 4\")\n",
"param.main.param.warning(\"Message 5\")"
]
},
{
"cell_type": "markdown",
"id": "e94c2fa9",
"metadata": {},
"source": [
"## Counting warnings\n",
"\n",
"Typically, a program will abort if an error is encountered, making such a condition hard to miss, but warning messages might be lost in a sea of informational, verbose, or debug messages. Param keeps track of how many times `.param.warning(...)` (or its alias `.param.log(param.WARNING, ...)`) has been called, and it is often useful to print out that value at the end of a program run:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "348f9d37",
"metadata": {},
"outputs": [],
"source": [
"print(f\"Run completed. {param.parameterized.warning_count} warnings were encountered.\")"
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/Outputs.ipynb 0000664 0000000 0000000 00000013724 14636363363 0020265 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "fa87315d",
"metadata": {},
"source": [
"# Outputs\n",
"\n",
"Parameters are typically used for the _inputs_ to a Parameterized objects, declaring as precisely as possible which inputs are allowed. You can also declare what _outputs_ are generated by a Parameterized, using `@param.output`. At present, Param itself does not use output declarations internally, but they can be queried by Param-based programs to allow safe chaining of Parameterized objects into pipelines, such as for the [boxflow](https://github.com/ioam/boxflow) dataflow programming system or the multi-page pipelines in [Panel](https://panel.holoviz.org/how_to/pipeline/index.html). \n",
"\n",
"`@param.output` annotates a method on a Parameterized class to declare that it returns one or more outputs of a specified type. As a simple example, this declaration indicates that the given function returns a number:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e4d4a11c",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class P(param.Parameterized):\n",
" a = param.Number(default=5, bounds=(0, 10))\n",
" b = param.Number(default=5, bounds=(0, 10))\n",
"\n",
" @param.output(param.Number)\n",
" def product(self):\n",
" return self.a * self.b\n",
" \n",
"p = P(a=2, b=3)\n",
"p.product()"
]
},
{
"cell_type": "markdown",
"id": "0dafc330",
"metadata": {},
"source": [
"If a program wants to know if the output from object `p` is suitable for connecting to an input of some other object `q`, it can query this output type:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "461604e5",
"metadata": {},
"outputs": [],
"source": [
"p.param.outputs()"
]
},
{
"cell_type": "markdown",
"id": "787ac37c",
"metadata": {},
"source": [
"This return value is of the form _name_: (_type_, _method_, _index_), which here indicates that:\n",
"- object `p` generates one output called `product` \n",
"- `product` is of type `param.Number`\n",
"- `product` can be generated by invoking method `p.product()` \n",
"- `product` will be returned directly as a single value by the method (indicated by an index of `None`; otherwise the index would indicate the position of this particular output in a tuple returned by the method)\n",
"\n",
"An automated program could use this information to decide whether the output from one Parameterized is suitable for connecting to the input of another.\n",
"\n",
"The above example is typical, but let's review the other output declarations accepted by `@param.output`. The simplest declaration declares the method returns an object of the same name as the method, without any type guarantees:\n",
"\n",
"```python\n",
"@param.output()\n",
"def product(self): return self.a * self.b\n",
"```\n",
"\n",
"More commonly, a parameter type will be specified as above, indicating that this method returns a value of that type, again defaulting to the method name:\n",
"\n",
"```python\n",
"@param.output(param.Number())\n",
"def product2(self): return self.a * self.b\n",
"```\n",
"\n",
"The output name can be declared explicitly as a keyword argument if desired, e.g. if the method name is not a suitable output name:\n",
"\n",
"```python\n",
"@param.output(result=param.Number())\n",
"def __call__(self): return self.a * self.b\n",
"```\n",
"\n",
"Multiple outputs may be declared using keywords mapping from output name to the type:\n",
"\n",
"```python\n",
"@param.output(prod_num=param.Number(), prod_str=param.String())\n",
"def products(self): \n",
" prod = self.a * self.b\n",
" return prod, str(prod)\n",
"```\n",
"\n",
"`@param.output` also accepts Python object types, which will be upgraded to a ClassSelector:\n",
"\n",
"```python\n",
"@param.output(int)\n",
"def int_product(self): return int(self.a * self.b)\n",
"```\n",
"\n",
"We can see these various options in action:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e7863dc4",
"metadata": {},
"outputs": [],
"source": [
"class Q(param.Parameterized):\n",
" a = param.Number(default=5, bounds=(0, 10))\n",
" b = param.Number(default=5, bounds=(0, 10))\n",
"\n",
" @param.output()\n",
" def product(self): return self.a * self.b\n",
"\n",
" @param.output(param.Number())\n",
" def product2(self): return self.a * self.b\n",
"\n",
" @param.output(result=param.Number())\n",
" def __call__(self): return self.a * self.b\n",
"\n",
" @param.output(prod_num=param.Number(), prod_str=param.String())\n",
" def products(self): \n",
" prod = self.a * self.b\n",
" return prod, str(prod)\n",
"\n",
" @param.output(int)\n",
" def int_product(self): return int(self.a * self.b)\n",
"\n",
"q=Q()\n",
"q"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8265c0b4",
"metadata": {},
"outputs": [],
"source": [
"q.param.outputs()"
]
},
{
"cell_type": "markdown",
"id": "3a68b349",
"metadata": {},
"source": [
"Here, you can see that there are _two_ outputs from `products()`, one of type Number and one of type String, and that they are in the order (number, string) in the tuple. The other outputs are all a single result returned directly from that method, with the indicated types (defaulting to `Parameter`) and names. Annotating outputs in this way can help you build large, flexible systems for connecting Parameterized objects together into larger data or computational structures."
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/Parameter_Types.ipynb 0000664 0000000 0000000 00000123424 14636363363 0021705 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "7e085e53",
"metadata": {},
"source": [
"# Parameter types\n",
"\n",
"You can get some of the benefit of Param from Parameter and Parameterized alone, such as having constant or readonly parameters, parameter value inheritance, and parameter docstrings. However, you'll typically want a more specialized Parameter type so that you can enforce type and bounds restrictions and enable suitable behavior specialized for that type of parameter. Param ships with a large set of pre-defined more-specific Parameter types, and additional custom parameters can and should be added for any domain-specific parameter types needed.\n",
"\n",
"The predefined types are organized into a class hierarchy where each type is a subclass of Parameter:\n",
"\n",
"- [String](#strings): String value, optionally constrained by a regular expression\n",
"- [Color](#colors): A hex string specifying an RGB color, or a standard named color\n",
"- [Boolean](#booleans): True or False (or None, if allowed)\n",
" * [Event](#invocations): True/False parameter used to trigger actions (see [Dependencies and watchers](Dependencies_and_Watchers.ipynb)).\n",
"- [Dynamic](#numbers): Base class for values that can be set to a callable that returns a concrete value\n",
" * [Number](#numbers): Any type of numeric value\n",
" - [Integer](#numbers): Positive or negative integer value\n",
" - [Magnitude](#numbers): Positive value in the inclusive range 0.0,1.0\n",
" - [Date](#numbers): Date or datetime type\n",
" - [CalendarDate](#numbers): Date (not datetime)\n",
"- [Tuple](#tuples): Python tuple of a fixed length and optional fixed type\n",
" * [NumericTuple](#tuples): Python tuple of a fixed length and a numeric type\n",
" - [XYCoordinates](#tuples): Position in an x,y plane\n",
" - [Range](#tuples): A numeric range or interval\n",
" * [DateRange](#tuples): A range of dates or datetimes\n",
" * [CalendarDateRange](#tuples): A range of dates (not datetimes)\n",
"- [List](#lists): A list of objects, potentially of a fixed, min, or max length\n",
" * [HookList](#lists): A list of callables, for calling user-defined code at a processing stage\n",
"- [Path](#paths): A POSIX-style string specifying the location of a local file or folder\n",
" * [Filename](#paths): A POSIX-style string specifying the location of a local file\n",
" * [Foldername](#paths): A POSIX-style string specifying the location of a local folder\n",
"- [SelectorBase](#selectors): Abstract superclass covering various selector parameter types\n",
" * [Selector](#selectors): One object selected out of a provided ordered list of objects\n",
" - [FileSelector](#selectors): One filename selected out of those matching a provided glob\n",
" - [ListSelector](#selectors): Multiple objects selected out of a provided list of objects\n",
" - [MultiFileSelector](#selectors): Multiple filenames selected out of those matching a provided glob\n",
" * [ClassSelector](#classselectors): An instance or class of a specified Python class or superclass\n",
" - [Dict](#classselectors): A Python dictionary\n",
" - [Array](#classselectors): NumPy array\n",
" - [Series](#classselectors): A Pandas Series\n",
" - [DataFrame](#classselectors): A Pandas DataFrame\n",
"- [Callable](#invocations): A callable object, such as a function.\n",
" * [Action](#invocations): A callable with no arguments, ready to invoke\n",
"- [Composite](#invocations): A list of other attributes or parameters of this class, settable and readable as a group"
]
},
{
"cell_type": "markdown",
"id": "e9787a67",
"metadata": {},
"source": [
"The full behavior of these types is covered in the [Reference Manual](https://param.holoviz.org/reference.html#param-module). Here we will discuss the major categories of Parameter type and how to use them, including examples of what each type does _not_ allow (labeled `with param.exceptions_summarized():`). Each of these classes is also suitable for subclassing to create more specialized types enforcing your own specific constraints. After reading about Parameters in general, feel free to skip around in this page and only look at the Parameter types of interest to you!"
]
},
{
"cell_type": "markdown",
"id": "0edcb97b",
"metadata": {},
"source": [
"## Strings\n",
"\n",
"- [`param.String`](param.String): String value, with optional regular expression (regex) constraints\n",
"\n",
"A [`param.String`](param.String) may be set to any Python string value by default, or it may be constrained to match a provided regular expression `regex`. Like all other Parameters, it can optionally also `allow_None`, which will be true by default if the default value is None."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "625ce570",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class S(param.Parameterized):\n",
" s = param.String('Four score', regex='[A-Z][a-z][a-z][a-z ]*')\n",
"\n",
"s = S()\n",
"s.s"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b72b6908",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" s.s = 5"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1dac26fc",
"metadata": {},
"outputs": [],
"source": [
"s.s = 'Forever after'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "924db709",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" s.s = 'four of spades'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d094459d",
"metadata": {},
"outputs": [],
"source": [
"ip_regex = '^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'\n",
"email_regex = '^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$'\n",
"\n",
"class I(param.Parameterized):\n",
" ip_address = param.String('192.1.0.1', regex=ip_regex)\n",
" email = param.String('example@me.com', regex=email_regex)\n",
"i = I()\n",
"i.ip_address"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "79585706",
"metadata": {},
"outputs": [],
"source": [
"i.ip_address=\"10.0.0.2\"\n",
"i.email = \"user@gmail.com\""
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "82efd99d",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" i.ip_address='192.x.1.x'"
]
},
{
"cell_type": "markdown",
"id": "65f03a46",
"metadata": {},
"source": [
"## Colors\n",
"\n",
"- `param.Color`: Named color or hex RGB string (with or without a # prefix)\n",
"\n",
"\n",
"A Color parameter specifies one of the standard [web color names](https://www.w3.org/TR/css-color-3/#svg-color) or an arbitrary hex RGB string. To support only hex RGB strings, specify `allow_named=False`.\n",
"\n",
"lemonchiffon"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "93ab3a83",
"metadata": {},
"outputs": [],
"source": [
"class C(param.Parameterized):\n",
" c = param.Color('#EEFF00')\n",
"\n",
"c = C()\n",
"c.c"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9db80a95",
"metadata": {},
"outputs": [],
"source": [
"c.c = 'lemonchiffon'\n",
"c.c"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e14d63f1",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" c.c = 'puce'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b8d880a5",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" c.c = '#abcdefg'"
]
},
{
"cell_type": "markdown",
"id": "91e09506",
"metadata": {},
"source": [
"## Booleans\n",
"\n",
"- `param.Boolean`: A True or False value (or None, if allow_None is true)\n",
"\n",
"A Boolean may be True or False. Like all other Parameters, it can optionally also `allow_None`, which will be true by default if the default value is None."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7a145fab",
"metadata": {},
"outputs": [],
"source": [
"class B(param.Parameterized):\n",
" b = param.Boolean(True)\n",
" n = param.Boolean(None)\n",
"\n",
"b = B()\n",
"b.b"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cb91b352",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" b.b=1"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "da7a9a2f",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" b.b=None"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e5f68ef1",
"metadata": {},
"outputs": [],
"source": [
"b.n = True\n",
"b.n = None"
]
},
{
"cell_type": "markdown",
"id": "f31c0f1e",
"metadata": {},
"source": [
"## Numbers\n",
"\n",
"- `param.Number`: Python floats, int, and Numpy values.\n",
"- `param.Integer`: Python and Numpy integer values.\n",
"- `param.Magnitude`: Same as `param.Number(..., bounds=(0.0,1.0))`.\n",
"- `param.Date`: Date or datetime value of type `datetime.datetime`, `datetime.date`, or `numpy.datetime64`.\n",
"- `param.CalendarDate`: Date value of type `datetime.date`.\n",
"\n",
"A Number is the most common type of Parameter. All Numbers in param are of class Dynamic, which allows them to be set not just to a single value but to a value that can repeatedly be drawn from a distribution or a sequence. (See [Dynamic Parameters](Dynamic_Parameters.ipynb) for more information about using these dynamic features, which will not be further discussed here.) Any Number has a default value (potentially None if allowed) and optional bounds.\n",
"\n",
"There are two types of bounds: ``bounds`` and ``softbounds``. ``bounds`` are hard bounds: the parameter must have a value within the specified range. The default bounds are (None,None), meaning there are actually no hard bounds. One or both bounds can be set by specifying a value (e.g. `bounds=(None,10)` means there is no lower bound, and an upper bound of 10). Bounds are inclusive by default, but exclusivity can be specified for each bound by setting inclusive_bounds (e.g. `inclusive_bounds=(True,False)` specifies an exclusive upper bound). \n",
"\n",
"When not being dynamically generated, `bounds` are checked whenever a Number is created or set. Using a default value outside the hard bounds, or one that is not numeric, results in an exception. When being dynamically generated, bounds are checked when the value of a Number is _requested_ (since it has no specific numeric value when first set). A generated value that is not numeric, or is outside the hard bounds, results in an exception. \n",
"\n",
"A separate set of ``softbounds`` is present to indicate the _typical_ range of the parameter, but these bounds are not enforced by Param. Setting the soft bounds allows a user to know what ranges of values are likely to be useful and allows a GUI to know what values to display on sliders for the Number; `softbounds` are thus suggestions or hints rather than enforced limits. \n",
"\n",
"Similarly, an optional ``step`` value can be provided to indicate the granularity of this parameter. As for `softbounds`, Param does not force values to conform to the provided step value, but (if provided) the step can be queried by user code and used for parameter sweeps (starting at the `softbounds` low and incrementing in value by `step` until the `softbounds` high), or by GUI code to determine steps on a settings dial.\n",
"\n",
"Several convenience methods for working with bounds are provided:\n",
"- `get_soft_bounds()`: return the soft bounds (or hard bounds, if no soft bounds), for code that needs to know the typical range for this Parameter.\n",
"- `crop_to_bounds(val)`: crop the provided value to fit into the hard bounds.\n",
"- `set_in_bounds(obj,val)`: silently crop the given value into the legal range and set to the result, for building an API or user interface that accepts free-form input. \n",
"\n",
"Using Number parameters:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2ff07754",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class N(param.Parameterized):\n",
" n = param.Number(5.6, bounds=(0,None), softbounds=(None,50))\n",
" i = param.Integer(5, bounds=(0,50))\n",
" \n",
"a = N()\n",
"a.n=2\n",
"a.n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8e95f919",
"metadata": {},
"outputs": [],
"source": [
"N.param.n.set_in_bounds(a,-10)\n",
"a.n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c8463d63",
"metadata": {},
"outputs": [],
"source": [
"a.param.n.set_in_bounds(a,-5)\n",
"a.n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5db79041",
"metadata": {},
"outputs": [],
"source": [
"a.param.n.set_in_bounds(a,75)\n",
"a.n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "17a2faaf",
"metadata": {},
"outputs": [],
"source": [
"a.param.n.get_soft_bounds()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e887e3e4",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" a.n = -5"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3ae9ca52",
"metadata": {},
"outputs": [],
"source": [
"a.n = 500\n",
"a.n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "764dd765",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" a.i=5.7"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d3369af4",
"metadata": {},
"outputs": [],
"source": [
"import datetime\n",
"\n",
"class D(param.Parameterized):\n",
" d = param.CalendarDate(datetime.date(1900, 1, 1))\n",
" t = param.Date(datetime.datetime.fromisoformat('2002-12-25T00:00'))\n",
"\n",
"d = D()\n",
"d.d = datetime.date.fromisoformat('2000-01-01')\n",
"d.d"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "caef921b",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" d.d = 2022"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "995807bd",
"metadata": {},
"outputs": [],
"source": [
"d.t = datetime.date(1900, 1, 1)\n",
"d.t"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2c667efd",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" d.d = datetime.datetime.fromisoformat('2002-12-25T00:00')"
]
},
{
"cell_type": "markdown",
"id": "4847bc8b",
"metadata": {},
"source": [
"## Tuples"
]
},
{
"cell_type": "markdown",
"id": "0602f947",
"metadata": {},
"source": [
"- `param.Tuple`: Python tuple of a fixed length.\n",
"- `param.NumericTuple`: Python tuple of a fixed length, with numeric values.\n",
"- `param.XYCoordinates`: Python pair (2-tuple) of numeric values. Same as `param.NumericTuple(..., length=2)`, but semantically representing a 2D coordinate in a plane (e.g. for drawing programs or GUIs)\n",
"- `param.Range`: `NumericTuple` representing a numeric range with optional bounds and softbounds.\n",
"- `param.DateRange`: `Range` where the numeric type is a date or datetime (using same date types as `param.Date`).\n",
"- `param.CalendarDateRange`: `Range` where the numeric type is a `datetime.date`. \n",
"\n",
"A tuple Parameter accepts a Python tuple for the value. Tuple parameters have a fixed length, typically set by the default value of the parameter but settable as the `length` if the default value is None. Only a tuple of the specified length will be accepted when a value is set.\n",
"\n",
"There are many tuple types as listed above, accepting either any type, numeric types, datetimes, dates, etc. `Range` types support `bounds`, `softbounds`, `inclusive_bounds`, and `step` on the numeric values in the tuple, similar to [Number](#numbers) types."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "aa7494a7",
"metadata": {},
"outputs": [],
"source": [
"class T(param.Parameterized):\n",
" t = param.Range((-10,10), bounds=(-100,None), softbounds=(None,100))\n",
"b = T()\n",
"b.t"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "89b12646",
"metadata": {},
"outputs": [],
"source": [
"b.t = (50.2,50.3)\n",
"b.t"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b1f1f4c9",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" b.t = 5"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2e481b37",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" b.t = (5,5,5)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "03fb63e9",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" b.t = (5,\"5\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cebd0b19",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" b.t = (-500,500)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e01e474a",
"metadata": {},
"outputs": [],
"source": [
"import datetime\n",
"class D(param.Parameterized):\n",
" d = param.CalendarDateRange((datetime.date.fromisoformat('1900-01-01'),\n",
" datetime.date.fromisoformat('1910-12-31')))\n",
"c = D()\n",
"c.d"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b84a21ed",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" c.d=(1905, 1907)"
]
},
{
"cell_type": "markdown",
"id": "4befeab9",
"metadata": {},
"source": [
"## Lists"
]
},
{
"cell_type": "markdown",
"id": "76db67ce",
"metadata": {},
"source": [
"- `param.List`: A Python list of objects, usually of a specified type.\n",
"- `param.HookList`: A list of callable objects, for executing user-defined code at some processing stage\n",
"\n",
"List Parameters accept a Python list of objects. Typically the `item_type` will be specified for those objects, so that the rest of the code does not have to further check types when it refers to those values. Where appropriate, the `bounds` of the list can be set as (_min_length_, _max_length_), defaulting to `(0,None)`. Because List parameters already have an empty value ([]), they do not support `allow_None`.\n",
"\n",
"A `param.HookList` is a list whose elements are callable objects (typically either functions or objects with a `__call__` method). A `HookList` is intended for providing user configurability at various stages of some processing algorithm or pipeline. At present, there is no validation that the provided callable takes any particular number or type of arguments."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e8351f51",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"class L(param.Parameterized):\n",
" ls = param.List([\"red\",\"green\",\"blue\"], item_type=str, bounds=(0,10))\n",
"\n",
"e = L()\n",
"e.ls"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6dbabdcb",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" e.ls = [1,2]"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5accd58c",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" e.ls = [str(i) for i in range(20)]"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "811df0b8",
"metadata": {},
"outputs": [],
"source": [
"class multi_stage_example(param.Parameterized):\n",
" before = param.HookList()\n",
" during = param.HookList()\n",
" after = param.HookList()\n",
" \n",
" values = param.List([1.5,-8.1,6.9,100.0], item_type=float)\n",
" \n",
" def __call__(self):\n",
" for h in self.before: h(self)\n",
" s = 0\n",
" for v in self.values:\n",
" v_ = v\n",
" for h in self.during: v_ = h(v_)\n",
" s += v_\n",
" for h in self.after: h()\n",
" return s\n",
"\n",
"ex = multi_stage_example()\n",
"ex()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "51c77d9e",
"metadata": {},
"outputs": [],
"source": [
"def validate(obj):\n",
" for i in obj.values:\n",
" if i<0:\n",
" print(\"Negative value found in argument\")\n",
"\n",
"m = multi_stage_example(before=[validate])\n",
"\n",
"m()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "db1b102e",
"metadata": {},
"outputs": [],
"source": [
"from math import fabs\n",
"\n",
"ex.during=[abs]\n",
"ex()"
]
},
{
"cell_type": "markdown",
"id": "3571b46b",
"metadata": {},
"source": [
"## Paths\n",
"\n",
"- `param.Path`: A POSIX-style string specifying the location of a local file or folder\n",
"- `param.Filename`: A POSIX-style string specifying the location of a local file\n",
"- `param.Foldername`: A POSIX-style string specifying the location of a local folder\n",
"\n",
"A Path can be set to a string specifying the path of a file or folder. In code, the string should be specified in POSIX (UNIX) style, using forward slashes / and starting from / if absolute or some other character if relative. When retrieved, the string will be in the format of the user's operating system. \n",
"\n",
"Relative paths are converted to absolute paths by searching for a matching filename on the filesystem in the current working directory (obtained with `os.getcwd()`). If `search_paths` is provided and not empty, the folders in that list are searched for the given filename, in order, returning the absolute path for the first match found by appending the provided path to the search path. An IOError is raised if the file or folder is not found. If `search_paths` is empty (the default), the file or folder is expected to be in the current working directory.\n",
"\n",
"When `check_exists` is set to `False` (default is `True`) the provided path can optionally exist. This is for instance useful to declare an output file path that is meant to be created at a later stage in a process. In the default case the path must exist, on Parameter instantiation and setting.\n",
"\n",
"Either a file or a folder name is accepted by `param.Path`, while `param.Filename` accepts only file names and `param.Foldername` accepts only folder names."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cb449123",
"metadata": {},
"outputs": [],
"source": [
"class P(param.Parameterized):\n",
" p = param.Path('Parameter_Types.ipynb')\n",
" f = param.Filename('Parameter_Types.ipynb')\n",
" d = param.Foldername('lib', search_paths=['/','/usr','/share'])\n",
" o = param.Filename('output.csv', check_exists=False)\n",
" \n",
"p = P()\n",
"p.p"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d3d08aa2",
"metadata": {},
"outputs": [],
"source": [
"p.p = '/usr/lib'\n",
"p.p"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f5a50ea9",
"metadata": {},
"outputs": [],
"source": [
"p.f"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "79112698",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" p.f = '/usr/lib'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "266a525c",
"metadata": {},
"outputs": [],
"source": [
"p.d"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6da8779e",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" p.d = 'Parameter_Types.ipynb'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "53225144",
"metadata": {},
"outputs": [],
"source": [
"p.o # the output file doesn't exist yet"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "863b9817",
"metadata": {},
"outputs": [],
"source": [
"with open(p.o, 'w') as f:\n",
" f.write('Param is awesome!')\n",
"\n",
"p.o # it now exists, getting its value resolve the full file path"
]
},
{
"cell_type": "markdown",
"id": "573079ef",
"metadata": {},
"source": [
"## Selectors\n",
"\n",
"- `param.Selector`: One object selected out of a provided ordered list of objects\n",
"- `param.ListSelector`: Multiple objects selected out of a provided list of objects\n",
"- `param.FileSelector`: One filename selected out of those matching a provided glob\n",
"- `param.MultiFileSelector`: Multiple filenames selected out of those matching a provided glob\n",
"\n",
"The value of a Selector is one or more items from a set of allowed values. All Selector types must implement `get_range()`, providing a concrete list of available options for the value.\n",
"\n",
"A `param.Selector` accepts a list or dictionary of `objects`, and has a single default (current) value that must be one of those objects. If not otherwise specified, the default will be the first item from the list or dictionary. \n",
"\n",
"Providing the objects as a list is appropriate for selecting among a set of strings, or among a set of Parameterized objects that each have a \"name\" parameter. That way, a UI that lets users select by string will have a suitable string available for each object to let the user make a choice between them.\n",
"\n",
"Otherwise, the objects should be provided as a _name_:_value_ dictionary, where the string name will be stored for use in such a UI, but is not otherwise accessed by Param. The values from setting and getting the parameter are always the actual underlying object, not the string names.\n",
"\n",
"To make it easier to modify the collection of `objects`, they are wrapped in a container that supports both list-style and dictionary-style methods. This approach ensures that there is a consistent API for updating the `objects` and that modifying the objects in place still triggers an event.\n",
"\n",
"If the list of available objects is not meant be exhaustive, you can specify `check_on_set=False` (which automatically applies if the initial list is empty). Objects will then be added to the `objects` list whenever they are set, including as the initial default. `check_on_set=False` can be useful when the predefined set of objects is not exhaustive, letting a user select from the existing list for convenience while also being able to supply any other suitable object they can construct. When `check_on_set=True`, the initial value (and all subsequent values) must be in the `objects` list.\n",
"\n",
"Because `Selector` is usually used to allow selection from a list of existing (instantiated) objects, `instantiate` is False by default, but you can specify `instantiate=True` if you want each copy of this Parameter value to be independent of other instances and superclasses.\n",
"\n",
"In cases where the objects in the list cannot be known when writing the Parameterized class but can be calculated at runtime, you can supply a callable (of no arguments) to `compute_default_fn`, and then ensure that at runtime you call `compute_default` on that Parameter to initialize the value.\n",
"\n",
"A `param.ListSelector` works just the same as a regular Selector, but the value is a _list_ of valid objects from the available objects, rather than just one. Each item in the list is checked against the `objects`, and thus the current value is thus a _subset_ of the `objects`, rather than just one of the objects.\n",
"\n",
"A `param.FileSelector` works like a regular Selector with the value being a filename and the `objects` being computed from files on a file system. The files are specified as a `path` [glob](https://docs.python.org/3/library/glob.html), and all filenames matching the glob are valid `objects` for the parameter.\n",
"\n",
"A `param.MultiFileSelector` is the analog of ListSelector but for files, i.e., again supporting a path glob but allowing the user to select a list of filenames rather than a single filename. The default value in this case is _all_ of the matched files, not just the first one."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "98852f74",
"metadata": {},
"outputs": [],
"source": [
"colors = [\"red\",\"green\",\"blue\"]\n",
"\n",
"class S(param.Parameterized):\n",
" o = param.Selector(objects=colors)\n",
" ls = param.ListSelector(colors[0:2], objects=colors)\n",
" \n",
"s = S()\n",
"s.o"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "49fb6839",
"metadata": {},
"outputs": [],
"source": [
"s.o = \"green\"\n",
"s.o"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b1d118a2",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" s.o = \"yellow\""
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2f08db09",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" s.o = 42"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2beac492",
"metadata": {},
"outputs": [],
"source": [
"s.ls"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9ddf7d53",
"metadata": {},
"outputs": [],
"source": [
"s.ls=['blue']\n",
"s.ls"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1c22dcd1",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" s.ls=['red','yellow']\n",
" s.ls"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "dc30268c",
"metadata": {},
"outputs": [],
"source": [
"class F(param.Parameterized):\n",
" f = param.FileSelector(path='/usr/share/*')\n",
" fs = param.MultiFileSelector(path='/usr/share/*')\n",
" \n",
"f = F()\n",
"f.f"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f4abfeee",
"metadata": {},
"outputs": [],
"source": [
"f.param.f.objects[0:3]"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b58509a6",
"metadata": {},
"outputs": [],
"source": [
"f.fs = f.param.fs.objects[0:2]\n",
"f.fs"
]
},
{
"cell_type": "markdown",
"id": "3084902c",
"metadata": {},
"source": [
"## ClassSelectors\n",
"\n",
"- `param.ClassSelector`: An instance or subclass of a class or tuple of classes\n",
"- `param.Dict`: A Python dictionary\n",
"- `param.Array`: NumPy array\n",
"- `param.Series`: A Pandas Series\n",
"- `param.DataFrame`: A Pandas DataFrame\n",
"\n",
"A ClassSelector has a value that is either an instance or a subclass of a specified Python `class_`. By default, requires an instance of that class, but specifying `is_instance=False` means that a subclass must be selected instead.\n",
"\n",
"Like Selector types, all ClassSelector types implement `get_range()`, in this case providing an introspected list of all the concrete (not abstract) subclasses available for the given class. If you want a class to be treated as abstract so that it does not show up in such a list, you can have it declare `__abstract=True` as a class attribute. In a GUI, the range list allows a user to select a type of object they want to create, and they can then separately edit the new object's parameters (if any) to configure it appropriately."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "70809e48",
"metadata": {},
"outputs": [],
"source": [
"class C(param.Parameterized):\n",
" e_instance = param.ClassSelector(default=ZeroDivisionError(\"1/0\"), class_=ArithmeticError)\n",
" e_class = param.ClassSelector(\n",
" default=ZeroDivisionError, class_=(ArithmeticError, LookupError),\n",
" is_instance=False\n",
" )\n",
" \n",
"c = C(e_class=OverflowError)\n",
"c.e_class, c.e_instance"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b3be8c3d",
"metadata": {},
"outputs": [],
"source": [
"c.param.e_instance.get_range()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "92c50c04",
"metadata": {},
"outputs": [],
"source": [
"c.param.e_class.get_range()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0b499411",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" c.e_class = Exception"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "150cc654",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" c.e_instance = ArithmeticError"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0d3d9c56",
"metadata": {},
"outputs": [],
"source": [
"c.e_instance = ArithmeticError()\n",
"c.e_instance"
]
},
{
"cell_type": "markdown",
"id": "dce7b733",
"metadata": {},
"source": [
"Various types of ClassSelector are provided for specific data types:\n",
"\n",
"- `param.Dict`: `class_=dict`, accepting a Python dictionary\n",
"- `param.Array`: `class=numpy.ndarray`, accepting a NumPy array\n",
"- `param.Series`: `class_=pandas.Series`, a Pandas Series. Accepts constraints on the number of `rows`, either as an integer length (e.g. `rows=10`) or a range tuple `rows=(2,4)`).\n",
"- `param.DataFrame`: `class_=pandas.DataFrame`, a Pandas DataFrame. Accepts constraints on the number of `rows` (as for `param.Series`) or `columns` (with numerical or range values as for `rows` or as a list of column names (which must appear in that order) or as a set of column names (which can appear in any order))."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "067f20c1",
"metadata": {},
"outputs": [],
"source": [
"import numpy as np, pandas as pd\n",
"\n",
"class D(param.Parameterized):\n",
" d = param.Dict(dict(a=1, b=\"not set\", c=2.0))\n",
" a = param.Array(np.array([1,-1]))\n",
" s = param.Series(pd.Series([1,-1]))\n",
" f = param.DataFrame(pd.DataFrame({'a':[1,2], 'b':[2,3], 'c':[4,5]}), rows=(2,None), columns=set(['a','b']))\n",
"\n",
"d = D()\n",
"d.d = {5:np.nan}\n",
"d.d"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a321de5d",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" d.d=[(\"a\",1)]"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "50f01ab8",
"metadata": {},
"outputs": [],
"source": [
"df = pd.DataFrame({'b':[-2,-3], 'a':[-1,-2]})\n",
"d.f = df\n",
"d.f"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "bb1097b7",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" df = pd.DataFrame({'a':[-2,-3], 'c':[-1,-2]})\n",
" d.f = df"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "44a2a32d",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" df = pd.DataFrame({'a':[-2], 'b':[-1]})\n",
" d.f = df"
]
},
{
"cell_type": "markdown",
"id": "dfbef370",
"metadata": {},
"source": [
"### `classlist` and `param.descendents`\n",
"\n",
"If you are building a GUI or some other mechanism allowing the user to choose a class or an instance of a specified class in a ClassSelector, you may want to construct a list of all subclasses or superclasses of the given class. To make it easy to traverse upwards or downwards in the inheritance hierarchy in this way, param provides the `classlist` and `param.descendents` functions. `classlist` provides a list of the superclasses of the provided object, including itself, in order from least to most specific:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f4b40d09",
"metadata": {},
"outputs": [],
"source": [
"from param.parameterized import classlist\n",
"\n",
"classlist(D)"
]
},
{
"cell_type": "markdown",
"id": "fbd3c5d3",
"metadata": {},
"source": [
"As you can see, `D` is a type of `Parameterized`, and a `Parameterized` is a type of Python object. Conversely (and typically more usefully), `param.descendents` provides a list of the subclasses of the provided object, including itself:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "abf691ca",
"metadata": {},
"outputs": [],
"source": [
"param.descendents(param.SelectorBase)"
]
},
{
"cell_type": "markdown",
"id": "7cfe3c7b",
"metadata": {},
"source": [
"As you can see, there are many subtypes of SelectorBase. This list is calculated from whatever subtypes are currently defined in this Python session. If you derive an additional subtype or load code that defines an additional subtype, this list will get longer, so you need to make sure that all such code has been executed before letting the user make a selection of a subtype."
]
},
{
"cell_type": "markdown",
"id": "bd887647",
"metadata": {},
"source": [
"## Invocations\n",
"\n",
"- `param.Callable`: A callable object, such as a function\n",
"- `param.Action`: A callable with no arguments, ready to invoke\n",
"- `param.Event`: Empty action, for use in triggering events for watchers\n",
"- `param.Composite`: Wrapper around other parameters, letting them be set as a tuple\n",
"\n",
"Invocation parameters are a loose group of types that either contain an executable (callable) object, are invoked to execute some other code, or are set to change the value of some other parameter(s) or attribute(s).\n",
"\n",
"A Callable may be set to any callable object, typically either a function or else an instance of a class that provides a `__call__` method. At present, there is no validation that the provided callable takes any particular number or type of arguments. Lambdas can be provided, but note that the resulting parameter value will no longer be picklable, so if you need to use pickling (`setstate` and `getstate`), be sure to use a named function instead.\n",
"\n",
"An Action is the same as a Callable, but is expected to have no arguments. In a GUI an Action is typically mapped to a button whose name or label is the name of this parameter. \n",
"\n",
"An Event Parameter has a Boolean value but is primarily intended for triggering events on its watchers. See [Dependencies and Watchers](Dependencies_and_Watchers.ipynb) for the details.\n",
"\n",
"A Composite Parameter has a value that is looked up from the value of a list of attributes of this class (which may or may not be parameters) and that when set changes the values of those other attributes or parameters. This type of Parameter can be useful for treating a set of related values as a group for setting purposes, but as individual parameters for code that reads from them. As of Param 1.10, Composite parameters have not been tested with watchers and dependencies and may not behave appropriately for such uses."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1f3b7fc2",
"metadata": {},
"outputs": [],
"source": [
"def identity(x): return x\n",
" \n",
"def print_time_of_day():\n",
" print(datetime.date.today())\n",
"\n",
"class A(param.Parameterized):\n",
" transformer = param.Callable(identity)\n",
" a = param.Action(print_time_of_day)\n",
" \n",
" def __call__(self, x):\n",
" return self.transformer(x)\n",
" \n",
"a = A()\n",
"a(5)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "70cd5a08",
"metadata": {},
"outputs": [],
"source": [
"def double(x):\n",
" return 2*x\n",
" \n",
"d = A(transformer=double)\n",
"d(5)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9c9aad93",
"metadata": {},
"outputs": [],
"source": [
"d.a()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "26927d79",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" d.a = 5"
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/ParameterizedFunctions.ipynb 0000664 0000000 0000000 00000010032 14636363363 0023254 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "2f8bed81",
"metadata": {},
"source": [
"# ParameterizedFunctions\n",
"\n",
"`Parameterized` classes and objects are full-featured substitues for Python objects, providing rich support and control for how attributes behave. What if you need similar features, but for functions rather than objects?\n",
"\n",
"Python functions don't directly support the various [language features like descriptors that Param builds on](How_Param_Works.ipynb), but you can instead make a Python class or object that _behaves_ like a function, while still supporting Parameters. To make that easier, Param provides an abstract class `ParameterizedFunction` that you can use as a superclass for any function-like object you want to write. A ParameterizedFunction automatically invokes its `__call__` method whenever it is instantiated. So, all you need to do is implement the `__call__` method with the implementation of your function. For example:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4c52a416",
"metadata": {},
"outputs": [],
"source": [
"from param import Parameter, ParameterizedFunction, ParamOverrides\n",
"\n",
"class multiply(ParameterizedFunction):\n",
" \"Function to multiply two arguments.\"\n",
"\n",
" left = Parameter(2, doc=\"Left-hand-side argument\")\n",
" right = Parameter(4, doc=\"Right-hand-side argument\")\n",
"\n",
" def __call__(self, **params):\n",
" p = ParamOverrides(self, params)\n",
" return p.left * p.right\n",
" \n",
"multiply()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "67e42bf5",
"metadata": {},
"outputs": [],
"source": [
"multiply(left=3, right=7)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "16f1938f",
"metadata": {},
"outputs": [],
"source": [
"multiply.left = 7\n",
"multiply(right = 10)"
]
},
{
"cell_type": "markdown",
"id": "0e00795d",
"metadata": {},
"source": [
"Here you can see that multiply acts like any other function that takes keyword arguments, but the arguments are now documented, potentially type checked, and have default values. \n",
"\n",
"This implementation depends on the separate object {py:class}`param.ParamOverrides`, which provides two-level lookup of parameter values: first on the arguments provided to the call, and then (if not provided) on the ParameterizedFunction instance. This way a user can choose to provide any or none of the arguments when the function (really, function object) is invoked. \n",
"\n",
"The `__call__` method can also take positional arguments, but in that case the class author would need to handle any mapping from those arguments to parameters there might be. `__call__` can also take extra keyword arguments beyond parameter values, but if so, you'll need to construct ParamOverrides as `p = ParamOverrides(self, params, allow_extra_keywords=True)`, then access the extra (non-Parameter) keywords in `p.extra_keywords` and process those explicitly."
]
},
{
"cell_type": "markdown",
"id": "99af9344",
"metadata": {},
"source": [
"## .instance()\n",
"\n",
"Usually, with a Parameterized object, you can modify values on the instance level, in addition to the class level shown above. Here, however, there is no instance to grab, because the ParameterizedFunction is called and evaluated, returning a value rather than the function object. If you want to grab an instance where you can set a value and then call the instance, you can use the `.instance()` method of a ParameterizedFunction:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "db166711",
"metadata": {},
"outputs": [],
"source": [
"multiply_by_10 = multiply.instance(right=10)\n",
"multiply_by_10(left=8)"
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/Parameters.ipynb 0000664 0000000 0000000 00000113443 14636363363 0020704 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "edc2a19c",
"metadata": {},
"source": [
"# Parameters and Parameterized objects\n",
"\n",
"Fundamentally, what Param does is allow you to control how certain user-visible attributes (\"parameters\") of a Python class or instance will behave when their value is get or set. A user of that class can set those attributes to control the class, but only if the mechanisms provided by Param and configured by the programmer allow it. In this way, Param allows the author of a class to implement and constrain what a user can do with that class or an instance of it, setting up a clear contract of what is and is not allowed, and how that attribute will behave. To do this, Param provides two main new types of Python object: `Parameter` objects, and `Parameterized` objects.\n",
"\n",
"A parameter is a special kind of Python class attribute. Setting a `Parameterized` class attribute to be a Parameter instance causes that attribute of the class (and the class's instances) to be treated as a parameter, not just an ordinary attribute. Parameters support special behavior, including dynamically generated parameter values, documentation strings, constant and read-only parameters, type or range checking at assignment time, and values dependent on those of other parameters.\n",
"\n",
"More concretely, a Python `Parameter` object inherits from `param.Parameter` and stores various metadata attributes describing how a corresponding Python attribute of a `Parameterized` object should behave. By convention, we will use a capital 'P' Parameter to refer to the Parameter object itself, and a lower-case 'p' parameter to refer to the Python attribute it controls (i.e., the Parameter's \"value\"). \n",
"\n",
"A `Parameterized` class is a Python class that inherits from `param.Parameterized` and can accept `Parameter` objects as class attributes. A `Parameterized` class or instance uses the `Parameter` objects to determine how the corresponding attribute should behave.\n",
"\n",
"There are many specific types of `Parameter` with different behavior, discussed in [Parameter Types](Parameter_Types.ipynb), but here we will cover the common behavior between _all_ Parameter types when used in a `Parameterized` object."
]
},
{
"cell_type": "markdown",
"id": "49c75fc9",
"metadata": {},
"source": [
"## Parameter metadata\n",
"\n",
"Each Parameter type can define additional behavior and associated metadata, but the metadata supported for all Parameter types includes:\n",
"\n",
"- **default**: Default value for this parameter at the class level, which will also be the value at the Parameterized instance level if it hasn't been set separately on the instance.\n",
"- **name**: String **name** of this parameter, which is typically determined by the attribute name of this Parameter in the owning Parameterized object, and is not set directly by a programmer.\n",
"- **label**: Optional long name used for a verbose listing; defaults to the **name**.\n",
"- **allow_None**: Whether this parameter accepts None as an allowed value, in addition to whatever other types it accepts. Automatically set to True if the default value of this Parameter is None.\n",
"- **doc**: Docstring describing this parameter, which can be used by automatic documentation systems.\n",
"- **constant**: Parameter whose value can only be changed at the class level or in a Parameterized constructor. Once the Parameterized instance has been created, the value is constant except in the context of `with param.edit_constant(obj)` (see below).\n",
"- **readonly**: Parameter whose value cannot be set by a user either on an instance or at the class level. Can still be changed inside a codebase by temporarily overriding this value, e.g. to report internal state.\n",
"- **instantiate**: Whether to deepcopy the default value into a Parameterized instance when it is created. False by default for Parameter and most of its subtypes, but some Parameter types commonly used with mutable containers default to `instantiate=True` to avoid interaction between separate Parameterized instances, and users can control this when declaring the Parameter (see below). \n",
"- **per_instance**: whether a separate Parameter instance will be created for every Parameterized instance created. Similar to `instantiate`, but applies to the Parameter object rather than to its value.\n",
"- **precedence**: Optional numeric value controlling whether this parameter is visible in a listing and if so in what order.\n",
"- **allow_refs**: Whether to allow the Parameter to accept references to other Parameters that will be dynamically resolved.\n",
"- **nested_refs**: Whether references should be resolved even when they are nested inside a container.\n",
"\n",
"Most of these settings (apart from **name**) are accepted as keyword arguments to the Parameter's constructor, with `default` mostly also accepted as the only positional argument:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "15441c20",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"from param import Parameter, Parameterized\n",
"\n",
"p = Parameter(default=42, doc=\"The answer\", constant=True)\n",
"p.default"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8972998f",
"metadata": {},
"outputs": [],
"source": [
"p.allow_None"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "40523986",
"metadata": {},
"outputs": [],
"source": [
"p.doc"
]
},
{
"cell_type": "markdown",
"id": "880c08d0",
"metadata": {},
"source": [
"## Parameter objects and instances\n",
"\n",
"In most cases, a Parameter will not be declared on its own as above; the Parameter object by itself is little more than a container for the metadata above. Until it is put into a class, most of those declarations are not meaningful, because what the Parameter object does is to specify how the corresponding Python attribute of that class should be handled. For example, we can define a Parameterized class with a couple of Parameter objects, and we'll then be able to access the corresponding attributes of that class:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4161f316",
"metadata": {},
"outputs": [],
"source": [
"class A(Parameterized):\n",
" question = Parameter(\"What is it?\", doc=\"The question\")\n",
" answer = Parameter(default=2, constant=True, doc=\"The answer\")\n",
" ultimate_answer = Parameter(default=42, readonly=True, doc=\"The real answer\")\n",
"\n",
"a = A(question=\"How is it?\", answer=\"6\")"
]
},
{
"cell_type": "markdown",
"id": "23141898",
"metadata": {},
"source": [
"Here, we created a Parameterized class `A`, with parameters `question` and `answer`, each with default values. We then instantiated a Python object `a` of type `A`. Without having to write a constructor for `A`, we were able to provide our own values for `question` and `answer`, while inheriting the default value of `ultimate_answer`. This approach gives a lot of (but not too much!) configurability to the user of this class, without much effort by the class author. Any values we provide at instantiation need to be allowed by the `Parameter` declaration; e.g. here we could not provide a value for `ultimate_answer` when declaring `a`, because that parameter is declared read only:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "016377f1",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" A(ultimate_answer=\"no\")"
]
},
{
"cell_type": "markdown",
"id": "876b69fa",
"metadata": {},
"source": [
"Now that we have a Parameterized instance `a`, we can access the attributes we defined just as if they were normal Python instance attributes, and we'll get the values we provided:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "76e87cfd",
"metadata": {},
"outputs": [],
"source": [
"a.question"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "372f24e5",
"metadata": {},
"outputs": [],
"source": [
"a.answer"
]
},
{
"cell_type": "markdown",
"id": "3206cfdb",
"metadata": {},
"source": [
"Meanwhile, the `Parameterized` _class_ `A` (not the instance `a`) still has the default values, accessible as class attributes and used for any future objects instantiated of type `A`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9954dc0e",
"metadata": {},
"outputs": [],
"source": [
"A.question"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c855c562",
"metadata": {},
"outputs": [],
"source": [
"A.answer"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8c59c6b5",
"metadata": {},
"outputs": [],
"source": [
"b = A()\n",
"b.answer"
]
},
{
"cell_type": "markdown",
"id": "b3589305",
"metadata": {},
"source": [
"If accessing the attribute always gives us a value whether on the instance or the class, what happened to the `Parameter` objects? They are stored on the Parameterized instance or class, and are accessible via a special `param` accessor object at either the instance or class levels, via attribute or key:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7786fe6d",
"metadata": {},
"outputs": [],
"source": [
"a.param['question']"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "700999a6",
"metadata": {},
"outputs": [],
"source": [
"a.param.question"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "766e3a42",
"metadata": {},
"outputs": [],
"source": [
"a.param.question.name"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e2ee5ef0",
"metadata": {},
"outputs": [],
"source": [
"a.param.question.default"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f92224e9",
"metadata": {},
"outputs": [],
"source": [
"A.param.question.default"
]
},
{
"cell_type": "markdown",
"id": "1399e0b3",
"metadata": {},
"source": [
"Once the Parameterized instance is created, the attributes can continue to be modified on it as often as you like, as long as the value is allowed by the `Parameter` object involved. E.g. `question` can still be changed, while `answer` is constant and cannot be changed after the `Parameterized` object has been instantiated:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1622066a",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" a.question = True\n",
" a.answer = 5"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e1232083",
"metadata": {},
"outputs": [],
"source": [
"a.question"
]
},
{
"cell_type": "markdown",
"id": "f9ecc506",
"metadata": {},
"source": [
"Note that if for some reason you do need to change the value of a constant parameter (typically inside of your Parameterized object's own code), you can do so using the `param.edit_constant` context manager:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "25f5da3e",
"metadata": {},
"outputs": [],
"source": [
"with param.edit_constant(a):\n",
" a.answer = 30\n",
"a.answer"
]
},
{
"cell_type": "markdown",
"id": "252aa858",
"metadata": {},
"source": [
"In most cases, the only time you need to worry about the difference between a Parameter and a regular Python attribute is when you first declare it; after that it will sit there happily behaving as instructed, noticeable only when a user attempts something the declarer of that Parameter has not allowed. You can safely leave the various metadata items at their defaults most of the time, but they are all there for when your particular application requires a certain behavior. "
]
},
{
"cell_type": "markdown",
"id": "0ce2b60e",
"metadata": {},
"source": [
"## Parameter inheritance\n",
"\n",
"`Parameter` objects and their metadata are inherited in a hierarchy of `Parameterized` objects. Let's see how that works:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3b743022",
"metadata": {},
"outputs": [],
"source": [
"class A(Parameterized):\n",
" question = Parameter(\"What is it?\", doc=\"The question\")\n",
" answer = Parameter(default=2, constant=True, doc=\"The answer\")\n",
" ultimate_answer = Parameter(default=42, readonly=True, doc=\"The real answer\")\n",
"\n",
"class B(A):\n",
" ultimate_answer = Parameter(default=84)\n",
"\n",
"b = B()\n",
"b.question"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e2171651",
"metadata": {},
"outputs": [],
"source": [
"A.question = \"How are you?\""
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "91292e0a",
"metadata": {},
"outputs": [],
"source": [
"b.question"
]
},
{
"cell_type": "markdown",
"id": "17692a63",
"metadata": {},
"source": [
"Here you can see that B inherits `question` from A, and as long as `question` has not been set explicitly on `b`, `b.question` will report the value from where that Parameter was defined, i.e. A in this case. If `question` is subsequently set on `b`, `b.question` will no longer be affected by the value in `A`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "a57b907a",
"metadata": {},
"outputs": [],
"source": [
"b.question = \"Why?\"\n",
"A.question = \"Who?\"\n",
"b.question"
]
},
{
"cell_type": "markdown",
"id": "fc265dfa",
"metadata": {},
"source": [
"As you can see, parameters not specified in B are still fully usable in it, if they were declared in a superclass. **Metadata associated with that parameter is also inherited**, if not explicitly overidden in `B`.\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0917eddf",
"metadata": {},
"outputs": [],
"source": [
"b.param.ultimate_answer.constant"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4c8c7b11",
"metadata": {},
"outputs": [],
"source": [
"b.param.ultimate_answer.readonly"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "86039127",
"metadata": {},
"outputs": [],
"source": [
"b.ultimate_answer"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "84dc2df9",
"metadata": {},
"outputs": [],
"source": [
"b.param.ultimate_answer.default"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4a549ab5",
"metadata": {},
"outputs": [],
"source": [
"b.param.ultimate_answer.doc"
]
},
{
"cell_type": "markdown",
"id": "f6bb48df",
"metadata": {},
"source": [
"Looking at the metadata values of `ultimate_answer` on `b` or `B` you can see that:\n",
"\n",
"- All the default metadata values like `constant`, `allow_none`, ..., were inherited from the base `Parameter` object provided by Param\n",
"- The `read_only` and `doc` metadata values were inherited from `A`\n",
"- The `default` metadata value of `ultimate_answer` in `B` overrode the value provided in `A`.\n",
"\n",
"Parameter inheritance like this lets you (a) use a parameter in many subclasses without having to define it more than once, and (b) control the value of that parameter conveniently across the entire set of subclasses and instances, as long as that attribute has not been set on those objects already. Using inheritance in this way is a very convenient mechanism for setting default values and other \"global\" parameters, whether before a program starts executing or during it.\n",
"\n",
"`help(b)` or `help(B)` will list all parameters. You can also prefix or suffix a Parameterized object with `?` in an IPython console/Notebook to display the help:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "dd711290-b6f0-4e9e-bbce-c400da27a3c2",
"metadata": {},
"outputs": [],
"source": [
"B?"
]
},
{
"cell_type": "markdown",
"id": "54ecbc24-14eb-4c07-8a00-0fb79b6241da",
"metadata": {},
"source": [
""
]
},
{
"cell_type": "markdown",
"id": "3683dec7",
"metadata": {},
"source": [
"## Parameter value instantiation\n",
"\n",
"So much of the parameter metadata is there to help you control whether and how the parameter value is instantiated on Parameterized objects as they are created or new Parameterized subclasses as they are defined. Depending on how you want to use that Parameter and what values it might take, controlling instantiation can be very important when mutable values are involved. While the default behavior shown above is appropriate for **immutable attributes**, what happens if the value (unlike Python strings) is mutable? Things get a lot more complex."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b9fa3c69",
"metadata": {},
"outputs": [],
"source": [
"s = [1, 2, 3]\n",
"\n",
"class C(Parameterized):\n",
" s1 = Parameter(s, doc=\"A sequence\")\n",
" s2 = Parameter(s, doc=\"Another sequence\")\n",
"\n",
"c = C()"
]
},
{
"cell_type": "markdown",
"id": "fe928bac",
"metadata": {},
"source": [
"Here, both parameters `s1` and `s2` effectively point to the same underlying sequence `s`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ba3863a5",
"metadata": {},
"outputs": [],
"source": [
"c.s1 is c.s2"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0b9004be",
"metadata": {},
"outputs": [],
"source": [
"s[1] *= 5"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "81f40ddf",
"metadata": {},
"outputs": [],
"source": [
"s"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e69157b7",
"metadata": {},
"outputs": [],
"source": [
"c.s1"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "344bae37",
"metadata": {},
"outputs": [],
"source": [
"c.s1[2] = 'a'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "baf5b9f6",
"metadata": {},
"outputs": [],
"source": [
"c.s1"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5c87a5d6",
"metadata": {},
"outputs": [],
"source": [
"c.s2"
]
},
{
"cell_type": "markdown",
"id": "08324f49",
"metadata": {},
"source": [
"As you can see, there is only one actual sequence here, and `s`, `s1`, and `s2` all point to it. In some cases such behavior is desirable, e.g. if the mutable object is a specific global list (e.g. a set of search paths) with a unique identity and all of the parameters are meant to point to that specific item. In other cases, it's the contents of the mutable item that are important, and no sharing of contents is intended. Luckily, Param supports that case as well, if you provide `instantiate=True` (default is `False`):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5c92d85f",
"metadata": {},
"outputs": [],
"source": [
"s = [1,2,3]\n",
"\n",
"class D(Parameterized):\n",
" s1 = Parameter(default=s, doc=\"A sequence\", instantiate=True)\n",
" s2 = Parameter(default=s, doc=\"Another sequence\", instantiate=True)\n",
"\n",
"d = D()"
]
},
{
"cell_type": "markdown",
"id": "325b9bbe",
"metadata": {},
"source": [
"Now, parameters `s1` and `s2` point to their own copies of the sequence, independent of each other and of the original argument `s`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4c245a25",
"metadata": {},
"outputs": [],
"source": [
"d.s1 is d.s2"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "509c07ac",
"metadata": {},
"outputs": [],
"source": [
"s *= 2"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "311dbcba",
"metadata": {},
"outputs": [],
"source": [
"s"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9e5c5336",
"metadata": {},
"outputs": [],
"source": [
"d.s1"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f9d142d7",
"metadata": {},
"outputs": [],
"source": [
"d.s1[2] = 'a'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3d9a12f0",
"metadata": {},
"outputs": [],
"source": [
"d.s2"
]
},
{
"cell_type": "markdown",
"id": "3792939f",
"metadata": {},
"source": [
"Of course, copying the data into each instance like that costs memory, and moreover prevents controlling all instances at once by setting a class attribute as we saw earlier, which is why `instantiate` is not True by default. As a rule of thumb, set `instantiate=True` if and only if (a) your Parameter can take mutable values, and (b) you want those values to be independent between Parameterized instances."
]
},
{
"cell_type": "markdown",
"id": "6cfed7ae",
"metadata": {},
"source": [
"## Parameter object instantiation\n",
"\n",
"`instantiate` controls how parameter _values_ behave, but similar issues arise for Parameter _objects_, which offer similar control via the `per_instance` metadata declaration. `per_instance` (`True` by default) provides a logically distinct Parameter object for every Parameterized instance, allowing each such instance to have different metadata for that parameter. For example, we can set the label separately for each instance without clobbering each other:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2f5af5da",
"metadata": {},
"outputs": [],
"source": [
"d1 = D()\n",
"d2 = D()\n",
"d1.param.s1.label = \"sequence 1\"\n",
"d2.param.s1.label = \"(sequence 1)\"\n",
"d2.param.s1.label"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9f224f3b",
"metadata": {},
"outputs": [],
"source": [
"d1.param.s1.label"
]
},
{
"cell_type": "markdown",
"id": "5ce34483",
"metadata": {},
"source": [
"This capability is useful for situations with dynamically updated metadata, e.g. if you need setting one parameter's value (e.g. 'Continent') to change the allowed values of another parameter (e.g. 'Country'). The underlying Parameter objects are copied lazily (only when actually changed), so that objects are not actually multiplied unless necessary. If you do want parameters to share a single Parameter object so that you can control its behavior globally, you can achieve that with `per_instance=False`, though the effects can be confusing in the same way as `instantiate=True` for mutable objects (above):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "787e9813",
"metadata": {},
"outputs": [],
"source": [
"class E(Parameterized):\n",
" a = Parameter(default=3.14, label=\"pi\", per_instance=False)\n",
"\n",
"e1 = E()\n",
"e2 = E()\n",
"e2.param.a.label = \"Pie\"\n",
"e1.param.a.label"
]
},
{
"cell_type": "markdown",
"id": "c2e3d4a7",
"metadata": {},
"source": [
"## Instantiating with shared parameters\n",
"\n",
"When creating a large collection of Parameterized objects of the same type, the overhead of having separate parameters for each object can be significant. If you want, you can create the objects to share parameter values for efficiency, and also so that you can easily change a value on all such objects at the same time. \n",
"\n",
"As an example, let's say you've defined a Parameter value to be independent, such that changing one instance's value will not affect the others:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5013fe69",
"metadata": {},
"outputs": [],
"source": [
"class S(param.Parameterized):\n",
" l = Parameter(default=[1,2,3], instantiate=True)\n",
"\n",
"ss = [S() for i in range(10)]\n",
"ss[0].l[2] = 5\n",
"ss[1].l"
]
},
{
"cell_type": "markdown",
"id": "6c7195fd",
"metadata": {},
"source": [
"Here changing the value of `l` on `ss[0]` doesn't affect `ss[1]` or any other instances.\n",
"\n",
"What if you as a user of this class are creating a very large number of similar objects and actually do want them to share the same parameter value, either to save memory or to make it easy to change all of their values at once? In that case you can use the context manager `shared_parameters`, and any Parameterized objects created within that context will share parameter values, such that changing one of them will affect all of them:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "37e160d4",
"metadata": {},
"outputs": [],
"source": [
"with param.shared_parameters():\n",
" ps = [S() for i in range(10)]\n",
" \n",
"ps[0].l[2] = 5\n",
"ps[1].l"
]
},
{
"cell_type": "markdown",
"id": "ed4e296f",
"metadata": {},
"source": [
"This approach can provide significant speedup and memory savings in certain cases, but should only be used for good reasons, since it can cause confusion for any code expecting instances to be independent as they have been declared."
]
},
{
"cell_type": "markdown",
"id": "678b7a0e",
"metadata": {},
"source": [
"## Displaying Parameterized objects\n",
"\n",
"Most of the important behavior of Parameterized is to do with instantiation, getting, and setting, as described above. Parameterized also provides a few public methods for creating string representations of the Parameterized object and its parameters:\n",
"\n",
"- `Parameterized.__str__()`: A concise, non-executable representation of the name and class of this object\n",
"- `Parameterized.__repr__()`: A representation of this object and its parameter values as if it were Python code calling the constructor (`classname(parameter1=x,parameter2=y,...)`)\n",
"- `Parameterize.param._repr_html_()`: A rich HTML representation of the object with its parameters listed in a table together with their metadata.\n",
"- `Parameterized.param.pprint()`: Customizable, hierarchical pretty-printed representation of this Parameterized and (recursively) any of its parameters that are Parameterized objects. See [Serialization and Persistence](Serialization_and_Persistence.ipynb) for details on customizing `pprint`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0a1521ba",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class Q(param.Parameterized):\n",
" a = param.Number(default=39, bounds=(0,50), doc='Number a')\n",
" b = param.String(default=\"str\", doc='A string')\n",
"\n",
"class P(Q):\n",
" c = param.ClassSelector(default=Q(), class_=Q, doc='An instance of Q')\n",
" e = param.ClassSelector(default=param.Parameterized(), class_=param.Parameterized, doc='A Parameterized instance')\n",
" f = param.Range(default=(0,1), doc='A range')\n",
"\n",
"p = P(f=(2,3), c=P(f=(42,43)), name=\"demo\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0b0d5b84",
"metadata": {},
"outputs": [],
"source": [
"p.__str__()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e119e92a",
"metadata": {},
"outputs": [],
"source": [
"p.__repr__()"
]
},
{
"cell_type": "markdown",
"id": "799c1eeb-71c2-40a3-ad06-fd3ed8eda501",
"metadata": {},
"source": [
"The HTML representation of a `Parameterized` instance or class is displayed when you call `.param` in a Notebook."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4c17a53b-3acc-4e6e-ab93-e5d09728e1c5",
"metadata": {},
"outputs": [],
"source": [
"p.param"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "64628d11-7f2c-4718-bd8a-7a381e282047",
"metadata": {},
"outputs": [],
"source": [
"P.param"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2ed3a3f0",
"metadata": {},
"outputs": [],
"source": [
"p.param.pprint(separator=\"\\n\")"
]
},
{
"cell_type": "markdown",
"id": "b0acf461",
"metadata": {},
"source": [
"Notice that in the case of a circular reference (`p.c = P(c=p)`) the representation will show an ellipsis (`...`) rather than recursively printing the subobject:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "22b09e5d",
"metadata": {},
"outputs": [],
"source": [
"p.c=P(c=p)\n",
"p.param.pprint()"
]
},
{
"cell_type": "markdown",
"id": "3830ace8",
"metadata": {},
"source": [
"## Parameterized namespace\n",
"\n",
"Param allows you to create Parameterized objects by inheriting from the `Parameterized` base class. Param has evolved over time to reduce its footprint and reserve as few as possible attributes on this namespace, to reduce the risk of name clashes and allow you to freely define your attribute names. Param reserves a few names that are described below, make sure not to override, unless it is stated it is allowed:\n",
"\n",
"- Public attributes:\n",
" - `name`: Parameterized classes and instances have a name `String` Parameter, that by default is set to the class name when accessed from the class and to the class name appended with a 5 digit when accessed from the instance. You can override this Parameter by your own `String` Parameter if you need to.\n",
" - `param`: Property that helps keep the Parameterized namespace clean and disambiguate between Parameter objects and parameter values, it gives access to a namespace that offers various methods (see the section below) to update and inspect the Parameterized object at hand.\n",
"- Private attributes:\n",
" - `_param__parameters`: Store the object returned by `.param` on the class\n",
" - `_param__private`: Store various internal data on Parameterized class and instances\n",
" - `_param_watchers` (deprecated in Param 2.0 and to be removed soon): Store a dictionary of instance watchers"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "01759e1b",
"metadata": {},
"outputs": [],
"source": [
"class P(param.Parameterized):\n",
" a = param.Number()\n",
" b = param.String()\n",
"\n",
"p = P()\n",
"print(f'{P.name=}, {p.name=}')"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e802c7c7",
"metadata": {},
"outputs": [],
"source": [
"def namespace(obj):\n",
" return [o for o in dir(obj) if not o.startswith('__')]"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5c702205",
"metadata": {},
"outputs": [],
"source": [
"namespace(P)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b74fb157",
"metadata": {},
"outputs": [],
"source": [
"namespace(p)"
]
},
{
"cell_type": "markdown",
"id": "23979d82",
"metadata": {},
"source": [
"## Other Parameterized methods\n",
"\n",
"Like `.param.pprint`, the remaining \"utility\" or convenience methods available for a `Parameterized` class or object are provided via the `.param` subobject:\n",
"\n",
"- `.param.update(**kwargs)`: Set parameter values from the given `param=value` keyword arguments (or a dict or iterable), delaying watching and dependency handling until all have been updated. `.param.update` can also be used as a context manager to temporarily set values, that are restored to their original values when the context manager exits."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1779f544",
"metadata": {},
"outputs": [],
"source": [
"p.param.update(a=0, b='start');\n",
"print(p.a, p.b)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f1508201",
"metadata": {},
"outputs": [],
"source": [
"with p.param.update(a=1, b='temp'):\n",
" print(f'In the context manager: {p.a=}, {p.b=}')\n",
"print(f'After the context manager exits: {p.a=}, {p.b=}')"
]
},
{
"cell_type": "markdown",
"id": "0b9e1d85",
"metadata": {},
"source": [
"- `.param.values(onlychanged=False)`: A dict of name,value pairs for all parameters of this object"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "fd7f0eca",
"metadata": {},
"outputs": [],
"source": [
"p.param.values()"
]
},
{
"cell_type": "markdown",
"id": "244a17d0",
"metadata": {},
"source": [
"- `.param.objects(instance=True)`: Parameter objects of this instance or class"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1baf4823",
"metadata": {},
"outputs": [],
"source": [
"p.param.objects()"
]
},
{
"cell_type": "markdown",
"id": "1c5085ea",
"metadata": {},
"source": [
"\n",
"- `.param.add_parameter(param_name,param_obj)`: Dynamically add a new Parameter to this object's class\n",
"- `.param.get_value_generator(name)`: Returns the underlying value-generating callable for this parameter, or the underlying static value if none\n",
"- `.param.force_new_dynamic_value(name)`: For a Dynamic parameter, generate a new value and return it\n",
"- `.param.inspect_value(name)`: For a Dynamic parameter, return the current value of the named attribute without modifying it.\n"
]
},
{
"cell_type": "markdown",
"id": "3e8ab618",
"metadata": {},
"source": [
"## Specialized Parameter types\n",
"\n",
"As you can see above, a `Parameter` provides a lot of power already on its own, but in practice you will want to use much more specific parameter types that reject invalid inputs and keep your code clean and simple. A specialized Parameter acts as a \"contract\" with the users of the code you write, declaring and defending precisely what configuration is allowed and how to achieve it. If you need to accept specific inputs like that but don't add an appropriate Parameter type, you'll be stuck adding exceptions and validation code throughout your codebase, whereas anything you can express at the Parameter level will be enforced automatically without any further checks or code.\n",
"\n",
"For instance, what if you want to accept a numeric parameter, but (for some reason) can only accept numbers that are even integers? You'll need a custom Parameter class to express a restriction like that. In this case you can do it by overriding the `_validate_value` method of the `Parameter` class:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "89c1d341",
"metadata": {},
"outputs": [],
"source": [
"import numbers\n",
"\n",
"class EvenInteger(param.Parameter):\n",
" \"\"\"Integer Parameter that must be even\"\"\"\n",
"\n",
" def _validate_value(self, val, allow_None):\n",
" super()._validate_value(val, allow_None)\n",
" if not isinstance(val, numbers.Number):\n",
" raise ValueError(\n",
" f\"EvenInteger parameter {self.name!r} must be a number, not {val!r}.\"\n",
" )\n",
" \n",
" if not (val % 2 == 0):\n",
" raise ValueError(\n",
" f\"EvenInteger parameter {self.name!r} must be even, not {val!r}.\"\n",
" )\n",
"\n",
"class P(param.Parameterized):\n",
" n = param.Number()\n",
" b = EvenInteger()\n",
" \n",
"p=P()\n",
"P(n=5, b=4)\n",
"P(b=4, n=5, name='P00003')"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "80fbb171",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" P(n=5, b=\"four\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "980b932b",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" P(n=5, b=5)"
]
},
{
"cell_type": "markdown",
"id": "cc659490",
"metadata": {},
"source": [
"Luckily, you don't often need to write a custom Parameter class like this, because the most common cases are already provided in Param, as listed in the [Parameter Types](Parameter_Types.ipynb) manual. If you need something more specific than the existing types, start with the one that comes closest to restricting its value to the desired set of values without excluding any allowable values. In this case all integer powers of 2 are also integers, so you'd start with `param.Integer` rather than `param.Parameterized` as above. You can then make a new subclass and add validation as above to further restrict the values to precisely what you allow. Here if you inherited from `param.Integer` you would no longer need to check if the input is a number, as `param.Integer` already does that as long as you call `super` as above. Your custom type can override any aspects of the Parameter if needed, e.g. to accept different items in the constructor, store additional data, add additional constraints, and so on. The existing Parameter types in `param/__init__.py` act as a rich source of examples for you to start with and crib from."
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/Reactive_Expressions.ipynb 0000664 0000000 0000000 00000110707 14636363363 0022745 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "3ecf9ffc-96a0-4457-bc89-43cac0099e01",
"metadata": {},
"source": [
"# Reactive Functions and Expressions"
]
},
{
"cell_type": "markdown",
"id": "9e973ee7",
"metadata": {},
"source": [
"In Param, multiple paradigms for dynamic behavior coexist. The [Dependencies and Watchers](Dependencies_and_Watchers.ipynb) guide delves into an imperative 'push' model, where explicit callbacks handle Parameter updates, often suited for GUI environments where user interactions drive state changes.\n",
"\n",
"Param 2.0 introduces a declarative, reactive model. Reactive expressions automatically update when their referenced Parameters change. This model encourages you to specify 'what' should happen, letting Param manage 'how,' thereby simplifying code logic and enhancing modularity. Unlike the 'push' model, which may require complex event orchestration, the reactive model emphasizes high-level relationships. This makes it versatile, scaling from simple to complex use cases. For instance, the reactive model is a good fit in data transformation pipelines and real-time dashboards, automatically updating dependent steps or visualizations when underlying Parameters change. The reactive approach allows you to focus on defining the transformation or relationship logic without worrying about the sequence of updates.\n",
"\n",
"This guide covers two main approaches to the reactive model: \n",
"1. **Reactive Expressions:** With `.rx`, create reactive proxies for Parameters or objects, which recompute as inputs change.\n",
"2. **Reactive Functions:** Using `.bind`, auto-invoked functions update when their inputs change, offering a more declarative alternative to `.watch()`."
]
},
{
"cell_type": "markdown",
"id": "b551f8cd",
"metadata": {},
"source": [
":::{note} The code in this guide is designed to be run incrementally to observe the behavior of reactive expressions. If you're reading a rendered version online, keep in mind that the entire page will have been executed, affecting the output of earlier lines. To fully experience the live updates, download this page as a Jupyter Notebook and run through it line by line."
]
},
{
"cell_type": "markdown",
"id": "7be71aa1",
"metadata": {},
"source": [
"## Getting Started\n",
"\n",
"Param's `rx` feature allows you to create reactive values and expressions, enabling immediate updates to your results as you interactively modify values, avoiding the need for explicit callbacks or managing state manually.\n",
"\n",
"Before we dive in to discover how `rx` works behind the scenes, let's get started with a concrete example of loading some data into a [Pandas](https://pandas.pydata.org) DataFrame and then displaying it:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "eaa1f75f",
"metadata": {},
"outputs": [],
"source": [
"import pandas as pd\n",
"import param\n",
"\n",
"from param import rx"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4833f209",
"metadata": {},
"outputs": [],
"source": [
"URL = 'https://datasets.holoviz.org/penguins/v1/penguins.csv'\n",
"nrows = rx(2)\n",
"df = rx(pd.read_csv(URL))\n",
"df.head(nrows)"
]
},
{
"cell_type": "markdown",
"id": "71463561",
"metadata": {},
"source": [
"Here, this is just the same code you'd normally use to make a DataFrame, except for `rx()` being used to mark `nrows` and `df` as being reactive. As you can see, the reactive DataFrame works like any other DataFrame, using `.head()` and any other DataFrame methods as usual. But now, let's see what happens if we update the value of `nrows`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e9ead350",
"metadata": {},
"outputs": [],
"source": [
"nrows.rx.value += 2"
]
},
{
"cell_type": "markdown",
"id": "349ae1e6-d07f-4106-924f-21fbf6a4b0f7",
"metadata": {},
"source": [
"Whoa! As long as you are running a Jupyter notebook with a live Python process, you should have seen the dataframe \"head\" output _in_ _the_ _previous_ _cell_ update to the new value of `nrows`. That's because the reactive `df` expression being displayed in that cell captures the full pipeline of operations, automatically re-running `head` because the `nrows` has now changed. \n",
"\n",
"We've done this without having to write any special callbacks or any new functions, instead using special Python objects that capture the operations you've invoked and replay them as needed when inputs change.\n",
"\n",
"These updates should happen immediately (not only when the code cell finishes executing):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "49b40993",
"metadata": {},
"outputs": [],
"source": [
"import time\n",
"\n",
"for i in range(5,10):\n",
" nrows.rx.value = i\n",
" time.sleep(1)"
]
},
{
"cell_type": "markdown",
"id": "374de653",
"metadata": {},
"source": [
"You should see the previous `df.head` output react to each time `nrows` is changed, updating to reflect the current state.\n",
"\n",
"Next, let's explore a more intricate example. Although it involves a more complex pipeline, the code remains similar to what you'd write for a non-reactive Pandas DataFrame. To confirm, you can simply remove the `rx` calls:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "298ad9dc-7099-4e4f-bf04-d296e0433109",
"metadata": {},
"outputs": [],
"source": [
"import numpy as np\n",
"\n",
"style = rx('color: white; background-color: {color}')\n",
"color = rx('darkblue')\n",
"\n",
"def highlight_max(s, props=''):\n",
" if s.dtype.kind not in 'f':\n",
" return np.full_like(s, False)\n",
" return np.where(s == np.nanmax(s.values), props, '')\n",
"\n",
"styled_df = df.head(nrows).style.apply(highlight_max, props=style.format(color=color), axis=0)\n",
"\n",
"styled_df"
]
},
{
"cell_type": "markdown",
"id": "6f837bce-a2c2-4479-9adb-0a824fd29085",
"metadata": {},
"source": [
"Here we've made two additional reactive values (`style` and `color`), and written a Pandas pipeline reacting to those values, using precisely the same syntax you would with a regular Pandas expression. Since `styled_df` is now a reactive Pandas expression, it will re-run whenever any of those changes. To see, try executing each of the following commands, one by one:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "16d46876-0ded-4770-bb71-fd972d8d9046",
"metadata": {},
"outputs": [],
"source": [
"color.rx.value = 'red'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "aa9f36b4",
"metadata": {},
"outputs": [],
"source": [
"nrows.rx.value += 2"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b3502bc8",
"metadata": {},
"outputs": [],
"source": [
"color.rx.value = 'darkblue'"
]
},
{
"cell_type": "markdown",
"id": "8082c9db",
"metadata": {},
"source": [
"In the code above, we made reactive strings, numbers, and DataFrame expressions. You can also make functions reactive, which lets you make the URL reactive as well:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "106363b4",
"metadata": {},
"outputs": [],
"source": [
"url = rx(URL)\n",
"df = rx(pd.read_csv)(url)\n",
"df.head(2)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "30d7e585",
"metadata": {},
"outputs": [],
"source": [
"url.rx.value = 'https://datasets.holoviz.org/gapminders/v1/gapminders.csv'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "742bd80f",
"metadata": {},
"outputs": [],
"source": [
"url.rx.value = URL"
]
},
{
"cell_type": "markdown",
"id": "60db0a0a-a2be-4927-91a3-7cc8b10ea313",
"metadata": {},
"source": [
"In this case, `df` wraps the `read_csv` call generating the DataFrame, rather than a specific DataFrame instance. This demonstrates the flexibility of reactive expressions: you can write code as you usually would, but gain control over its reactivity.\n",
"\n",
"While we've been updating `.rx.value` manually in this notebook, you could easily replace these literals with widgets from ipywidgets or [HoloViz Panel](https://panel.holoviz.org/tutorials/basic/pn_rx.html), enabling you to create user-interactive, reactive applications with minimal effort."
]
},
{
"cell_type": "markdown",
"id": "1c566d1a",
"metadata": {},
"source": [
"## How it works\n",
"\n",
"So, how does reactive programming in Param actually work? The underlying mechanism leverage's Python's [operator overloading](https://www.geeksforgeeks.org/operator-overloading-in-python/), which allows us to redefine common operators like '`+`' to perform additional tasks. When you use these operators in reactive expressions, Param not only carries out the operation but also records it, establishing a dependency from the reactive variables involved to the resulting expression. This means that when a reactive variable is updated, Param automatically updates any expressions dependent on it.\n",
"\n",
"For instance, if you set up a reactive expression `j = i + 1`, where `i` has been made reactive, any change to `i` will automatically trigger an update in `j`, eliminating the need for manual event handling:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6a830ba9",
"metadata": {},
"outputs": [],
"source": [
"i = rx(1)\n",
"j = i + 1\n",
"print(f'i = {i.rx.value}')\n",
"print(f'j = {j.rx.value}')"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "bad87395",
"metadata": {},
"outputs": [],
"source": [
"i.rx.value = 7\n",
"print(f'i = {i.rx.value}')\n",
"print(f'j = {j.rx.value}')"
]
},
{
"cell_type": "markdown",
"id": "e089f478",
"metadata": {},
"source": [
"Without `rx()`, adding 1 to `i` would have immediately invoked integer addition in Python, assigning an integer 2 to `j`. However, because we made `i` a reactive expression, what happens is that `i` stores its input value on an internal attribute called `_obj`, while overloading `+` to not just calculate `i + 1`, but also return another reactive object that records the operation (`i + 1`). This stores the dependency so that whenever `i` changes, the reactive object knows that it needs to update itself by re-executing `i + 1`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c5925184",
"metadata": {},
"outputs": [],
"source": [
"type(i), i._obj, j._operation"
]
},
{
"cell_type": "markdown",
"id": "51aed018",
"metadata": {},
"source": [
"When you access the `.value` attribute of `j`, it retrieves the most recent result of the expression `i + 1`, automatically reapplying the operation if `i` has changed. For more complicated scenarios, reactive expressions can chain multiple operations and method calls together, executing them in sequence to obtain the final outcome.\n",
"\n",
"In essence, reactive expressions are specialized Python objects that wrap standard objects. They record the operations you apply, and when an underlying reactive value changes, they automatically re-execute these operations. This eliminates the need for manually tracking and updating dependent variables, making it easier to build dynamic, responsive applications."
]
},
{
"cell_type": "markdown",
"id": "a48adb7e-c340-49e1-bec1-30ca6cc2eca2",
"metadata": {},
"source": [
"## Limitations\n",
"\n",
"So does Python really allow _all_ operations to be overloaded so that a reactive expression works precisely like the underlying objects? \n",
"\n",
"Nearly, but not quite. For technical reasons, certain operations cannot be implemented in this way:\n",
"\n",
"- Python requires the `len` operation to return an integer, not a deferred reactive integer\n",
"- The Python `is` statement always checks the immediate identity of its two operands, so it cannot be deferred reactively\n",
"- Logical operators like `and`, `or`, `not`, and `in` are required to return Boolean types rather than deferred, reactive Boolean types\n",
"- No overloading is available for control flow keywords like `if`, `elif`, and `else` or ternary conditional expressions (i.e. `a if condition else b`), and so those actions cannot be captured for later reactive execution\n",
"- Iteration keywords like `for` or `while` can only be overloaded to some extent, specifically for fixed-length collections; other types of iteration cannot be captured for later reactive execution\n",
"\n",
"However, Param's reactive expressions offer workarounds for these limitations through special methods under the `.rx` namespace to avoid confusion with the underlying object's own methods. We'll cover these methods in the next section."
]
},
{
"cell_type": "markdown",
"id": "227a230b-98b2-4097-8a6d-798ddb63b74a",
"metadata": {},
"source": [
"## Special Methods on `.rx`\n",
"\n",
"To circumvent the limitations explained above, the `.rx` namespace provides reactive versions of the operations that can't be made reactive through overloading:\n",
"\n",
"- `.rx.and_`: Reactive version of `and`.\n",
"- `.rx.bool`: Reactive version of `bool()`.\n",
"- `.rx.in_`: Reactive version of `in`, testing if the value is in the provided collection.\n",
"- `.rx.is_`: Reactive version of `is`, testing the object identity against another object.\n",
"- `.rx.is_not`: Reactive version of `is not`, testing the absence of object identity with another object.\n",
"- `.rx.len`: Reactive version of `len()`, returning the length of the expression\n",
"- `.rx.map`: Applies a function to each item in a collection.\n",
"- `.rx.not_`: Reactive version of `not`.\n",
"- `.rx.or_`: Reactive version of `or`.\n",
"- `.rx.pipe`: Applies the given function (with static or reactive arguments) to this object.\n",
"- `.rx.updating`: Returns a boolean indicating whether the expression is currently updating.\n",
"- `.rx.when`: Generates a new expression that only updates when the provided dependency updates.\n",
"- `.rx.where`: Returns either the first or the second argument, depending on the current value of the expression.\n",
"\n",
"Unlike their corresponding standard Python equivalent, each of these returns a reactive expression that can thus be combined with other reactive expressions to make reactive pipelines."
]
},
{
"cell_type": "markdown",
"id": "d9aaee66-05f2-44ee-b287-c5eaf4622c3b",
"metadata": {},
"source": [
"#### `.rx.and_(arg)`\n",
"\n",
"Applies the `and` operator to the output of the reactive expression and the argument returning a new expression:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0dd7a685-1d2a-4f33-81d0-8d65feee2224",
"metadata": {},
"outputs": [],
"source": [
"rx(True).rx.and_(False)"
]
},
{
"cell_type": "markdown",
"id": "6b568713-8fb0-46b7-877e-cfe4f43ebc8c",
"metadata": {},
"source": [
"Unlike the bitwise `and` operator (`&`) this has the same semantics as the `and` keyword."
]
},
{
"cell_type": "markdown",
"id": "dcbf07d6-e53b-4658-86c7-15caf8eb540d",
"metadata": {},
"source": [
"#### `.rx.in_(arg)`\n",
"\n",
"Reactively checks if the current value is `.in_` the other collection"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "938583e7-c519-4c50-9f95-dc4099262a95",
"metadata": {},
"outputs": [],
"source": [
"rx(2).rx.in_([1, 2, 3])"
]
},
{
"cell_type": "markdown",
"id": "fb3697e6-0413-44cd-916a-dae665eb263b",
"metadata": {},
"source": [
"#### `.rx.is_(arg)`\n",
"\n",
"Reactively checks if the identity of the current value is the same as the argument to `.is_`"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0db8bc66-bf5b-4214-b3de-063ec6d53523",
"metadata": {},
"outputs": [],
"source": [
"rx(None).rx.is_(None)"
]
},
{
"cell_type": "markdown",
"id": "819249de-513d-4286-9a6f-ed14adba70bc",
"metadata": {},
"source": [
"#### `.rx.is_not(arg)`\n",
"\n",
"Reactively checks if the identity of the current value is not the same as the argument to `.is_not`"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "93db5be8-2023-4a67-83f0-329d0dea69d1",
"metadata": {},
"outputs": [],
"source": [
"rx(None).rx.is_not(None)"
]
},
{
"cell_type": "markdown",
"id": "9cba7f57-bc62-47bd-9cfd-b66c13d9f0e2",
"metadata": {},
"source": [
"#### `.rx.len()`\n",
"\n",
"Returns the length of the object as a reactive expression"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b9552875-905a-49d8-a1a3-6a824aeb1988",
"metadata": {},
"outputs": [],
"source": [
"obj = rx([1, 2, 3])\n",
"obj.rx.len()"
]
},
{
"cell_type": "markdown",
"id": "9531ef4c-28d9-48cd-8707-e0658b0ecc9e",
"metadata": {},
"source": [
"#### `.rx.map(func, *args, **kwargs)`\n",
"\n",
"Maps the function to each item in a collection returned by the expression:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ee4cafb0-bb85-4bd3-b39f-4e705f369908",
"metadata": {},
"outputs": [],
"source": [
"rx([1, 2, 3]).rx.map(lambda v, mul: v*mul, mul=2)"
]
},
{
"cell_type": "markdown",
"id": "2cbff9fe-e16d-427d-ab1c-35da603ad693",
"metadata": {},
"source": [
"#### `.rx.or_(arg)`\n",
"\n",
"Applies `or` to the output of the reactive expression and the argument:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2e8bff49-1164-4747-a704-c96f64084c44",
"metadata": {},
"outputs": [],
"source": [
"rx(False).rx.or_('A value')"
]
},
{
"cell_type": "markdown",
"id": "f50c3ea6-aa75-4bb5-91f3-1b2b5f320465",
"metadata": {},
"source": [
"Unlike the bitwise `or` operator (`|`) this has the same semantics as the `or` keyword."
]
},
{
"cell_type": "markdown",
"id": "2bd115e5-44bd-4d4d-b78a-a552b4072562",
"metadata": {},
"source": [
"#### `.rx.pipe(func, *args, **kwargs)`\n",
"\n",
"Pipes the current value into a function as the first argument, passing in additional positional and keyword arguments if provided, and returning a reactive expression to replay that call as needed:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c393e1e5-e18a-4b50-b355-cb3d461c8de5",
"metadata": {},
"outputs": [],
"source": [
"def f(a, b): return a + b\n",
" \n",
"rx(1).rx.pipe(f, 2)"
]
},
{
"cell_type": "markdown",
"id": "ac92db62",
"metadata": {},
"source": [
"`.rx.pipe` can be used with any Python function. One common usage is for making type conversion functions reactive:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "34e985c6",
"metadata": {},
"outputs": [],
"source": [
"rx(8.5).rx.pipe(int)"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "116b865a",
"metadata": {},
"outputs": [],
"source": [
"rx(8.5).rx.pipe(str)"
]
},
{
"cell_type": "markdown",
"id": "376f5b3d-8bcd-4ad3-869d-cdee176e54d8",
"metadata": {},
"source": [
"#### `.rx.updating()`"
]
},
{
"cell_type": "markdown",
"id": "9334392f-61d0-4629-aae8-0c9a7935c6fa",
"metadata": {},
"source": [
"Returns a new expression that is True while the original expression is updating. Useful for performing some action while an expression is running.\n",
"\n",
"Here we create a simple expression that calls a `calculate` function which emulates a long running computation:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e132793e-b5ad-49bb-88d1-378a24451055",
"metadata": {},
"outputs": [],
"source": [
"expr = rx(1)\n",
"\n",
"def calculate(value):\n",
" time.sleep(1)\n",
" return value\n",
"\n",
"updating = expr.rx.pipe(calculate).rx.updating()\n",
"\n",
"updating"
]
},
{
"cell_type": "markdown",
"id": "7eac3901-b9e6-4020-8f74-5817561a187e",
"metadata": {},
"source": [
"When we update the expression the `updating` expression will temporarily toggle to True and then reset:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1432d82f-4e8d-4ab0-b7f3-4a63a203b797",
"metadata": {},
"outputs": [],
"source": [
"expr.rx.value += 1"
]
},
{
"cell_type": "markdown",
"id": "dfea7f35-f0fa-4bc0-954f-b01d5dcf9d6c",
"metadata": {},
"source": [
"#### `.rx.when(*conditions)`\n",
"\n",
"Useful when creating UIs to declare that the expression should only update when some other parameter changes, e.g. when a user clicks a button or triggers an expensive operation through some other mechanism.\n",
"\n",
"For instance, let's say we have some expensive function (here simulated using `time.sleep`). First, we bind parameters `a` and `b` to this function and create a reactive expression from this function."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b0b7e3cc-4c31-4208-8f0a-efa05cc6e13e",
"metadata": {},
"outputs": [],
"source": [
"import time\n",
"\n",
"def expensive_function(a, b):\n",
" print(f'multiplying {a=} and {b=}')\n",
" time.sleep(2)\n",
" return a * b\n",
"\n",
"a = rx(1)\n",
"b = rx(2)\n",
"\n",
"expensive_expr = rx(expensive_function)(a, b)"
]
},
{
"cell_type": "markdown",
"id": "24ef7256-904b-4e74-859a-39d30d391317",
"metadata": {},
"source": [
"The problem we face is that if we use this `expensive_expr` whenever `a` **or** `b` are changed, then the expensive computation gets triggered *twice* if we want to change both `a` _and_ `b`. To avoid unnecessary expense, we can gate the computation behind a third variable we'll name `gate`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "8396d27b-81be-4185-be83-16a7bcfe0e4f",
"metadata": {},
"outputs": [],
"source": [
"gate = rx(False)\n",
"gated_expr = expensive_expr.rx.when(gate)\n",
"\n",
"gated_expr"
]
},
{
"cell_type": "markdown",
"id": "0b9b464b-1582-499f-b4c0-e7fe8074d8eb",
"metadata": {},
"source": [
"We can now safely change variables `a` and `b` separately without triggering the computation:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7f1dd442-0c57-49e2-97b5-2369adb35a7b",
"metadata": {},
"outputs": [],
"source": [
"a.rx.value = 2\n",
"b.rx.value = 4\n",
"\n",
"gated_expr.rx.value"
]
},
{
"cell_type": "markdown",
"id": "a1443865-288a-4320-841c-586fcfea04ac",
"metadata": {},
"source": [
"But when we trigger the `run` parameter the expression will re-compute:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "85c2a7d1-ff76-4137-b9ce-24363177e120",
"metadata": {},
"outputs": [],
"source": [
"gate.rx.value = True\n",
"\n",
"gated_expr.rx.value"
]
},
{
"cell_type": "markdown",
"id": "d74f3645-5186-46b5-b85b-4e512cfae7bd",
"metadata": {},
"source": [
"#### `.rx.where(a, b)`\n",
"\n",
"Reactive ternary conditional. In non-reactive Python code you can write:\n",
"\n",
"```python\n",
"a if condition else b\n",
"``` \n",
"\n",
"to return value `a` or value `b` depending on some `condition`. However, Python does not allow overriding `if` to have special behavior for a reactive `condition`, and thus such an expression will immediately evaluate and return `a` or `b` rather than capturing this logic for later reactivity.\n",
"\n",
"So if we want to have a reactive conditional, we have to rewrite the expression using `where`. First, we will declare a reactive `condition` expression to wrap a Boolean value that we can change later:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "dd4f9569-b9a9-4d43-93cb-93ffba6ce927",
"metadata": {},
"outputs": [],
"source": [
"condition = rx(True)"
]
},
{
"cell_type": "markdown",
"id": "d0dff104-a095-4a97-806b-059b4c9aa622",
"metadata": {},
"source": [
"Now let's say we want to return either `a` or `b` depending on whether the `condition` is True or False. We can simply pass the values to `.where()`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e9a36314-9a79-4e74-83e8-137f86655999",
"metadata": {},
"outputs": [],
"source": [
"a = rx(1)\n",
"b = rx(2)\n",
"\n",
"ternary_expr = condition.rx.where(a, b)\n",
"ternary_expr"
]
},
{
"cell_type": "markdown",
"id": "88ef4e67-0fa4-45a7-8154-89f94183d3fe",
"metadata": {},
"source": [
"Since the initial value is `True` it returns the current value of `a`, which is `1`. However when we set the value to `False` it will return the value of `b`:\n"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2a1ce24c-e5b3-497d-83bc-5ba351ece9ef",
"metadata": {},
"outputs": [],
"source": [
"condition.rx.value = False\n",
"\n",
"ternary_expr.rx.value"
]
},
{
"cell_type": "markdown",
"id": "ddb05099-e774-4f53-a345-527e44bdb5de",
"metadata": {},
"source": [
"Importantly, if we now change `b` the result will be reflected by the expression, reactively unless we explicitly resolve the result:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5e275e74-1d17-40bf-9382-d02a1fed61ae",
"metadata": {},
"outputs": [],
"source": [
"b.rx.value = 5\n",
"\n",
"ternary_expr.rx.value"
]
},
{
"cell_type": "markdown",
"id": "ce3ce7b3-8163-45b9-a465-17efdbca5c21",
"metadata": {},
"source": [
"Here the expression value depends only on `b` thanks to the `where` condition, and thus changes to `a` will no longer trigger any downstream updates until the condition is reversed again."
]
},
{
"cell_type": "markdown",
"id": "4151d9d4-49aa-42b8-83fd-eea081fb127d",
"metadata": {},
"source": [
"#### Watching an expression\n",
"\n",
"In some cases you may want to trigger some side-effect based on the return value of an expression. The simplest way to achieve this is using the `.rx.watch` API, which mirrors the [`.param.watch` API](Dependencies_and_Watchers.ipynb#watchers). Using this API we can define a callback which runs whenever the expression outputs a new event:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b5f87127-4f6d-4806-a1cb-4e6444cc6bc8",
"metadata": {},
"outputs": [],
"source": [
"c = rx(1)\n",
"\n",
"c.rx.watch(lambda v: print(f'Output: {v}'))\n",
"\n",
"c"
]
},
{
"cell_type": "markdown",
"id": "f9ddc079-3ed2-47f0-962f-0c1f6d58553d",
"metadata": {},
"source": [
"Now if we update the expression we will see the output run:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cad29d4d-c893-4fb0-8f1a-11cc0c1b1c1b",
"metadata": {},
"outputs": [],
"source": [
"c.rx.value += 1"
]
},
{
"cell_type": "markdown",
"id": "1c87f6a2-d108-435b-9305-0160eec628d6",
"metadata": {},
"source": [
"It is also possible to call `.param.watch` without any arguments, which makes the expression evaluate eagerly."
]
},
{
"cell_type": "markdown",
"id": "73810468",
"metadata": {},
"source": [
"## Parameters and `param.bind`\n",
"\n",
"Reactive expressions are part of the [Param](https://param.holoviz.org) library, and behind the scenes, all the reactivity is implemented using Parameters and their [dependencies and watchers](https://param.holoviz.org/user_guide/Dependencies_and_Watchers.html) support. You can use reactive expressions without needing to learn about Parameters, but if you do use Parameters in your work, they interact seamlessly with reactive expressions, providing a powerful and convenient way to organize your code and your work. In this section we will show how to use Parameters and the `param.bind` function together with reactive expressions for a more structured approach to reactive programming.\n",
"\n",
"First, let's create a Parameterized class with a couple of Parameters:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f6bf6371-8dc8-4247-afaa-3ce872ed3371",
"metadata": {},
"outputs": [],
"source": [
"class Parameters(param.Parameterized): \n",
" a = param.Number(1)\n",
"\n",
" b = param.Number(0)\n",
"\n",
" run = param.Event()\n",
" \n",
"p = Parameters()"
]
},
{
"cell_type": "markdown",
"id": "cf4c375b",
"metadata": {},
"source": [
"Any of the parameters can be used as reactive expressions by calling `.rx()` on their Parameter object:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f8346eea",
"metadata": {},
"outputs": [],
"source": [
"expr = p.param.a.rx() + p.param.b.rx() + 3\n",
"expr"
]
},
{
"cell_type": "markdown",
"id": "5f316cfc",
"metadata": {},
"source": [
"Now if we update the Parameter, the result of the expression will update immediately:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2cc67793",
"metadata": {},
"outputs": [],
"source": [
"p.b = 5\n",
"print(expr.rx.value)"
]
},
{
"cell_type": "markdown",
"id": "7e5ff5e8",
"metadata": {},
"source": [
"You can thus use any Parameter in your reactive expressions, including Parameters from [HoloViz Panel](https://panel.holoviz.org/tutorials/basic/pn_rx.html) widgets. In fact, reactive expressions are natively supported in Panel."
]
},
{
"cell_type": "markdown",
"id": "874621cc",
"metadata": {},
"source": [
"### Binding Parameters to Functions\n",
"\n",
"While reactive expressions with `rx` offer a flexible way to define dynamic relationships between Parameters, they operate at a fairly abstract level, encapsulating the underlying transformations. This can sometimes make it challenging to isolate specific parts of a pipeline for debugging or performance optimization.\n",
"\n",
"Enter `param.bind`, which allows you to define functions that are automatically invoked when their input Parameters change. This serves as a bridge between the reactive `rx` model and the lower-level 'push' model. Unlike the 'push' model, where you would explicitly set up watchers and callbacks, `param.bind` simplifies the process by letting Param manage the mechanics, but also making the dependencies more transparent than in a purely `rx` approach.\n",
"\n",
"In essence, `param.bind` offers the declarative nature of reactive expressions and the explicitness of the 'push' model. This makes it particularly useful for complex applications where you might want the clarity of explicit function calls for key parts of your pipeline, but also wish to retain the high-level, declarative relationships offered by reactive expressions.\n",
"\n",
"To demonstrate this concept, let's define a simple Python function for adding numbers. We'll also include print statements to make it evident when the function is invoked:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7a4bde61",
"metadata": {},
"outputs": [],
"source": [
"def add(a, b):\n",
" print(f'add: {a}+{b}={a+b}')\n",
" return a + b\n",
"\n",
"add(3, 7)"
]
},
{
"cell_type": "markdown",
"id": "1c4434e7-9b5d-4a5b-b9de-c444dae42e36",
"metadata": {},
"source": [
"Now we can use `param.bind` to \"bind\" parameters `a` and `b` to the `add` function's arguments to create a reactive function:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c0a4c64e-ee64-405d-bace-605551b34234",
"metadata": {},
"outputs": [],
"source": [
"reactive_add = param.bind(add, p.param.a, p.param.b)\n",
"\n",
"reactive_add"
]
},
{
"cell_type": "markdown",
"id": "9094768c-5a39-448e-9721-e6253a2a55cb",
"metadata": {},
"source": [
"As you can see, `reactive_add` works just like `add`, in that it adds two arguments, but in this case, it's taking the value of the `a` and `b` Parameters of `p`. Parameter `a` has been \"bound\" to the first argument and `b` to the second, and if either of them changes, the result changes. So if we change `p.a` to 5, the output above reacts immediately."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f7cd00ac-02a2-4e0c-bc98-7ce9739ed55b",
"metadata": {},
"outputs": [],
"source": [
"p.a += 4"
]
},
{
"cell_type": "markdown",
"id": "9a0e5412-b13f-42aa-bb21-4bf6f289510b",
"metadata": {},
"source": [
"We can also call the reactive function explicitly to return the current result as a concrete, no longer reactive value:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "1e026152-1772-4437-8165-dd9788edd1fb",
"metadata": {},
"outputs": [],
"source": [
"reactive_add()"
]
},
{
"cell_type": "markdown",
"id": "16d5e9ec",
"metadata": {},
"source": [
"The difference between `reactive_add` and `reactive_add()` is that the first one is a function, whose display will automatically update in IPython/Jupyter, while the second is a specific number (the result of calling that function a single time, never to be updated further):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9f1c1879",
"metadata": {},
"outputs": [],
"source": [
"print(type(reactive_add), type(reactive_add()))"
]
},
{
"cell_type": "markdown",
"id": "03d62757-8b3f-4d67-b1a9-5759194408a2",
"metadata": {},
"source": [
"`param.bind` follows the semantics of Python's `functools.partial`, and so if you only partially bind the required arguments, you'll get a function of the remaining arguments:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "88870bf0-1d5e-42e9-9c59-b538070ad701",
"metadata": {},
"outputs": [],
"source": [
"add_b = param.bind(add, p.param.a)\n",
"add_b"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d516b3dc",
"metadata": {},
"outputs": [],
"source": [
"add_b(5)"
]
},
{
"cell_type": "markdown",
"id": "1b0ead79",
"metadata": {},
"source": [
"Note that you can bind any accepted type to make a reactive function, not just Parameters, but static values won't trigger reactive updates (here 38 will always be the same value, while the result will depend on the current value of `p.param.a`)."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4badba81",
"metadata": {},
"outputs": [],
"source": [
"param.bind(add, p.param.a, b=38)"
]
},
{
"cell_type": "markdown",
"id": "d1f2b719-b80e-4fca-b78e-534971eee92e",
"metadata": {},
"source": [
"Bound functions update their outputs reactively when displayed, but what if you want to use one in a reactive expression? You can easily do that if you call `.rx()` on a fully bound function to get a reactive expression to work with:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "6b4e1c1a-8d19-4e4f-beae-042f01d4e41a",
"metadata": {},
"outputs": [],
"source": [
"param.bind(add, p.param.a, p.param.b).rx() / 2"
]
},
{
"cell_type": "markdown",
"id": "1272daed",
"metadata": {},
"source": [
"As you can see, you can use bound functions to get reactivity if you prefer to write specific functions, or you can use reactive expressions to capture computations without writing function definitions, or you can combine the two as needed. Feel free to use the approach that best meets your needs!\n",
"\n",
"And overall, hopefully, you can see that Param's reactive support provides a natural and powerful way to capture your computations in a way that can be replayed automatically whenever inputs change, making it a convenient basis for building interactive applications and computations."
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/References.ipynb 0000664 0000000 0000000 00000033075 14636363363 0020664 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "5d4a9beb-65c0-47dd-8afc-14b2c448f0b9",
"metadata": {},
"source": [
"# Reactive References\n",
"\n",
"Building on previous discussion about the dual roles of a `Parameter` - as both a value holder and a metadata container - let's explore how parameters can go a step further by acting as dynamic references to other parameters (and other, more advanced, reactive references). What we mean by this is that parameters do not have to refer to a specific static value but can reference another object and update reactively when its value changes. \n",
"\n",
"## Parameter References\n",
"\n",
"In the simplest case, when a parameter is configured with `allow_refs=True`, it can be given another `Parameter` as its value and it will automatically mirror its current value . This capability enables more intricate relationships between parameters, allowing for automatic value synchronization and forming the basis for reactive programming:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e45694e1-9503-488f-8797-531b18d3502d",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class U(param.Parameterized):\n",
" \n",
" a = param.Number()\n",
" \n",
"class V(param.Parameterized):\n",
" \n",
" b = param.Number(default=None, allow_refs=True)\n",
"\n",
"u = U(a=3.14)\n",
"v = V(b=u.param.a)\n",
"\n",
"v.b"
]
},
{
"cell_type": "markdown",
"id": "5c5cbfee-a199-4ffb-8e35-f0b543916ff2",
"metadata": {},
"source": [
"By declaring that `V.b` allows references we have made it possible to pass the Parameter `U.a`, which means `v.b` will reflect the value of `u.a`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3926d917-7334-45b4-8a49-4b9baf558d50",
"metadata": {},
"outputs": [],
"source": [
"u.a = 1.57\n",
"\n",
"v.b"
]
},
{
"cell_type": "markdown",
"id": "33744151-91c0-4d65-b84e-9a2678dc5eeb",
"metadata": {},
"source": [
"This unidirectional link will be in effect until something else tries to set the value:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "345e5b1e-a191-44b0-8c8f-48908b4332a2",
"metadata": {},
"outputs": [],
"source": [
"v.b = 14.1\n",
"u.a = 13.2\n",
"\n",
"v.b"
]
},
{
"cell_type": "markdown",
"id": "b8f1dd08-a91d-4e83-bb12-dd2447c8fad8",
"metadata": {},
"source": [
"In other words, if the value is overridden from the outside the link will be automatically removed.\n",
"\n",
"Simple references are resolved when `allow_refs=True` but to allow nested references we separately have to set `nested_refs=True`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e3ad5e4c-e8f1-4a16-b800-a06e434f2f65",
"metadata": {},
"outputs": [],
"source": [
"class W(V):\n",
" \n",
" c = param.List(allow_refs=True, nested_refs=True)\n",
" \n",
"u1 = U(a=3)\n",
"u2 = U(a=13)\n",
"\n",
"w = W(c=[u1.param.a, u2.param.a]) \n",
"\n",
"w.c"
]
},
{
"cell_type": "markdown",
"id": "2f52c6d5-dad7-4d38-8b0f-1364123b8e17",
"metadata": {},
"source": [
"When we modify either `u1.a` or `u2.a`, `w.c` will update:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e739d5f3-c762-4971-8386-48c5ed89e701",
"metadata": {},
"outputs": [],
"source": [
"u1.a = 7\n",
"\n",
"w.c"
]
},
{
"cell_type": "markdown",
"id": "46039ee7-93a7-44d8-b1bb-a9c1ed7f87a9",
"metadata": {},
"source": [
"## Other reference types"
]
},
{
"cell_type": "markdown",
"id": "32f2429f-fbff-4906-b3b0-4db7c3a9aa2b",
"metadata": {},
"source": [
"Note that `Parameter` types are not the only types of valid references. The full list of valid references include:\n",
"\n",
"- Class and instance `Parameter` objects\n",
"- [Functions or methods with dependencies](Dependencies_and_Watchers.ipynb#dependencies) added using `param.depends`\n",
"- [Reactive Functions](Reactive_Expressions.ipynb#parameters-and-param-bind) using `param.bind`\n",
"- [Reactive expressions](Reactive_Expressions.ipynb) declared using `param.rx`\n",
"- [(Asynchronous) generators](Generators.ipynb)\n",
"- Custom objects transformed into a valid reference with a hook registered with `param.parameterized.register_reference_transform`.\n",
"\n",
"There are two utility functions which allow resolving all parameters a reference depends on and the current value of the reference:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "da0cbf1c-e8b3-4d3a-9974-0c0e6ec1d2b0",
"metadata": {},
"outputs": [],
"source": [
"from param.parameterized import resolve_ref, resolve_value\n",
"\n",
"resolve_ref(u1.param.a), resolve_value(u1.param.a)"
]
},
{
"cell_type": "markdown",
"id": "9856dd01-153f-4f87-9acc-3f951592a475",
"metadata": {},
"source": [
"## Skipping Reference Updates\n",
"\n",
"Since references are resolved eagerly whenever one of the dependencies change we may run into situations where we want to control when a reference is updated. Specifically we may want to skip resolving a reference if one of the inputs does not meet some condition or only if a certain event is triggered.\n",
"\n",
"Let's see how we can configure this. Here we will create a class `W` with parameters `a` and `b` and a `run` event. We then define a function to `add` parameters `a` and `b` but only if the `run` event is active. To do this we can raise a `param.Skip` exception in the function."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "d04c62cc-8bab-46d6-9a4a-9c645d1d6510",
"metadata": {},
"outputs": [],
"source": [
"class W(param.Parameterized):\n",
" \n",
" a = param.Number()\n",
" \n",
" b = param.Number()\n",
"\n",
" run = param.Event()\n",
"\n",
"w = W(a=0, b=2)\n",
"\n",
"def add(a, b, run):\n",
" if not run:\n",
" raise param.Skip\n",
" return a + b"
]
},
{
"cell_type": "markdown",
"id": "a5ab6ca1-e220-405d-a8cf-89c276a6aa7e",
"metadata": {},
"source": [
"We can now bind all three parameters to the function:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "62af2167-e8cf-4099-8921-36d8a34b2a2b",
"metadata": {},
"outputs": [],
"source": [
"v = V(b=param.bind(add, w.param.a, w.param.b, w.param.run))\n",
"\n",
"v.b"
]
},
{
"cell_type": "markdown",
"id": "f28c3c42-bd6f-46e1-b269-fa6d13d0bbbd",
"metadata": {},
"source": [
"Even though we initialized `v.b` with a reference it will not resolve this reference until we trigger a `run` event:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "28c13ab5-4616-4a42-8cff-f82ba9599e8f",
"metadata": {},
"outputs": [],
"source": [
"w.param.trigger('run')\n",
"\n",
"v.b"
]
},
{
"cell_type": "markdown",
"id": "751e6786-7140-4a91-a430-6de35150f55c",
"metadata": {},
"source": [
":::{caution}\n",
"`Skip` exceptions are a useful tool for handling control flow in an application, however they should only be raised when writing a reactive reference and never be used in place of a real exception in your business logic. For example, when writing a function that fetches some data, you should raise specific exceptions and then catch those in the function that you are using as a reference and raise the `Skip` from there, e.g.:\n",
"\n",
"```python\n",
"def fetch_data(url):\n",
" response = requests.get(url)\n",
" json = response.json()\n",
" if 'data' in json: \n",
" raise ValueError(\"JSON response did not contain expected 'data' field.\")\n",
" return json['data']\n",
"\n",
"def data_ref(url):\n",
" try:\n",
" data = fetch_data(url)\n",
" except Exception:\n",
" raise Skip\n",
" return data\n",
"```\n",
":::"
]
},
{
"cell_type": "markdown",
"id": "6ffd34f8-211c-4945-95b8-e87ec712e028",
"metadata": {},
"source": [
"## Composable classes through references\n",
"\n",
"One common problem that occurs when writing classes where one object depends on the parameters of some other object is that the objects end up having to reference each other. This introduces dependencies between the two classes and leads to less composable abstractions and it only gets worse as you add more classes to the mix.\n",
"\n",
"Let's illustrate this with an example, say we have an investment portfolio and want to determine how much it is worth in our local currency and how much capital gains taxes we owe on our profit. We obtain these values from some external objects called `Forex` and `TaxSchedule`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "11cf2cca-fcb3-4684-af9e-9b1ff476efe2",
"metadata": {},
"outputs": [],
"source": [
"class Forex(param.Parameterized):\n",
"\n",
" exchange_rate = param.Number(default=1.125)\n",
"\n",
" ...\n",
"\n",
"class TaxSchedule(param.Parameterized):\n",
"\n",
" capital_gains = param.Number(default=0.25)\n",
"\n",
" ...\n",
"\n",
"forex = Forex(exchange_rate=1.14)\n",
"tax_schedule = TaxSchedule(capital_gains=0.25)"
]
},
{
"cell_type": "markdown",
"id": "b44d1a47-c5e1-492c-9f48-027179ca180e",
"metadata": {},
"source": [
"Without references we would now be forced to structure our `Portfolio` class to reference both the `forex` and `tax_schedule` objects because that's the only way we could cleanly depend on the values:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "355b840f-8acc-43c6-b46e-d34e21799779",
"metadata": {},
"outputs": [],
"source": [
"class Portfolio(param.Parameterized):\n",
"\n",
" foreign_value = param.Number()\n",
"\n",
" local_value = param.Number()\n",
"\n",
" taxes_owed = param.Number()\n",
"\n",
" forex = param.ClassSelector(class_=Forex)\n",
"\n",
" tax_schedule = param.ClassSelector(class_=TaxSchedule)\n",
"\n",
" @param.depends('foreign_value', 'forex.exchange_rate', watch=True, on_init=True)\n",
" def _update_local(self):\n",
" self.local_value = self.foreign_value * self.forex.exchange_rate\n",
"\n",
" @param.depends('local_value', 'tax_schedule.capital_gains', watch=True, on_init=True)\n",
" def _update_taxes(self):\n",
" self.taxes_owed = self.local_value * self.tax_schedule.capital_gains\n",
"\n",
"portfolio = Portfolio(foreign_value=12000, forex=forex, tax_schedule=tax_schedule)\n",
"\n",
"portfolio"
]
},
{
"cell_type": "markdown",
"id": "391e8070-4798-4104-90a6-fcfa15fce096",
"metadata": {},
"source": [
"Not only does our `Portfolio` class now have to know about these other objects but it also has to make significant assumptions about it, e.g. the naming of the `exchange_rate` and `capital_gains` parameter names is now hard coded in the actual class definition.\n",
"\n",
"References allow us to declare only the subset of parameter values our class cares about and does so without having to make any reference to anything external through it, the class becomes agnostic to the exact provider of the value."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3c538cfb-5101-47a1-864d-b7c252af0087",
"metadata": {},
"outputs": [],
"source": [
"class Portfolio(param.Parameterized):\n",
"\n",
" foreign_value = param.Number()\n",
"\n",
" local_value = param.Number()\n",
"\n",
" taxes_owed = param.Number()\n",
"\n",
" exchange_rate = param.Number(allow_refs=True)\n",
"\n",
" capital_gains = param.Number(allow_refs=True)\n",
"\n",
" @param.depends('foreign_value', 'exchange_rate', watch=True, on_init=True)\n",
" def _update_local(self):\n",
" self.local_value = self.foreign_value * self.exchange_rate\n",
" \n",
" @param.depends('local_value', 'capital_gains', watch=True, on_init=True)\n",
" def _update_taxes(self):\n",
" self.taxes_owed = self.local_value * self.capital_gains\n",
"\n",
"portfolio = Portfolio(\n",
" foreign_value=12000,\n",
" exchange_rate=forex.param.exchange_rate,\n",
" capital_gains=tax_schedule.param.capital_gains\n",
")\n",
"\n",
"portfolio"
]
},
{
"cell_type": "markdown",
"id": "ff72fa97-9f08-45ed-864b-503fb19b224f",
"metadata": {},
"source": [
"As we have discovered reactive references are a powerful tool not only to link two parameters together but unlock the ability to express a whole host of dynamic behavior through a simple, declarative syntax. The various valid reference types make it possible to everything from [using generators](Generators.ipynb) to push new updates to a parameter periodically or merely in sequence to expressing complex dependencies between two or more parameters with a [simple reactive expression](ReactiveExpressions.ipynb). Lastly, they ensure that you can write composable components without incorporating complex dependencies between objects into your classes themselves."
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/Serialization_and_Persistence.ipynb 0000664 0000000 0000000 00000065507 14636363363 0024613 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "61c98db5",
"metadata": {},
"source": [
"# Serialization and Persistence\n",
"\n",
"Parameterized objects are declarative, explicitly defining a set of values for their parameters. This set of values constitutes the (parameter) state of the object, and this state can be saved (\"serialized\"), transmitted (if appropriate), and restored (\"deserialized\") in various ways, so that object state can be sent from one Python session to another, restored from disk, configured using a text file, and so on.\n",
"\n",
"Param offers several independent serialization mechanisms for a Parameterized object, each used for very different purposes:\n",
"- **Pickle**: creates a Python [pickle](https://docs.python.org/3/library/pickle.html) file containing not just the Parameters, but potentially any other state of the object. A pickle file is not human readable, and is not always portable between different python versions, but it is highly complete, capturing both parameter values and also non-Parameter attributes of an object. Useful for saving the entire state of a complex object and restoring it. All objects used in pickling need to be restorable, which puts some restrictions on Parameter values (e.g. requiring named functions, not lambdas).\n",
"- **JSON**: captures the state as a JSON text string. Currently and probably always limited in what can be represented, but human readable and easily exchanged with other languages. Useful for sending over a network connection, saving simple state to disk for restoring later, etc.\n",
"- **script_repr**: generates a string representation in the form of Python code that, when executed, will instantiate Parameterized objects having similar state. Useful for capturing the current state in a compact, human-readable form suitable for manual editing to create a Python file. Not all Parameters will have values representable in this way (e.g. functions defined in the current namespace will not show their function definition), but this representation is generally a reasonable human-readable starting point for hand editing. "
]
},
{
"cell_type": "markdown",
"id": "385b4ac1",
"metadata": {},
"source": [
"## Pickling Parameterized objects\n",
"\n",
"Param supports Python's native [pickle](https://docs.python.org/3/library/pickle.html) serialization format. Pickling converts a Python object into a binary stream of bytes that can be stored on disk, and unpickling converts a previously pickled byte stream into an instantiated Python object in the same or a new Python session. Pickling does not capture the actual Python source code or bytecode for functions or classes; instead, it assumes you will have the same Python source tree available for importing those definitions during unpickling and only stores the fully qualified path to those definitions. Thus pickling requires that you use named functions defined in separate importable modules rather than lambdas (unnamed functions) or other objects whose code is defined only in the main namespace or in a non-importable python script. \n",
"\n",
"Apart from such limitations, pickling is the most rich and _fully featured_ serialization option, capable of capturing the full state of an object even beyond its Parameter values. Pickling is also inherently the _least portable_ option, because it does include all the details of this internal state. The resulting .pkl files are not human readable and are not normally usable outside of Python or even across Python versions in some cases. Pickling is thus most useful for \"snapshots\" (e.g. for checkpoint-and-restore support) for a particular software installation, rather than for exporting, archiving, or configuration. See the [comparison with JSON](https://docs.python.org/3/library/pickle.html#comparison-with-json) to help understand some of the tradeoffs involved in using pickles. \n",
"\n",
"### Using pickling\n",
"\n",
"Let's look at an example of pickling and unpickling a Parameterized object:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "965dba56",
"metadata": {},
"outputs": [],
"source": [
"import param, pickle, time\n",
"from param.parameterized import default_label_formatter\n",
"\n",
"class A(param.Parameterized):\n",
" n = param.Number(39)\n",
" l = param.List([\"a\",\"b\"])\n",
" o = param.ClassSelector(class_=param.Parameterized)\n",
" \n",
" def __init__(self, **params):\n",
" super(A,self).__init__(**params)\n",
" self.timestamp = time.time()\n",
" \n",
"a = A(n=5, l=[1,\"e\",[2]], o=default_label_formatter.instance())\n",
"a, a.timestamp"
]
},
{
"cell_type": "markdown",
"id": "05c87f9b",
"metadata": {},
"source": [
"Here we created a Parameterized object `a` containing another Parameterized object nested in parameter `o`, with state in `self.timestamp` and not just in the Parameter values. To save this state to a file on disk, we can do a pickle \"dump\" and then delete the object so that we are sure it's no longer around:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "99e9fc90",
"metadata": {},
"outputs": [],
"source": [
"with open('data.pickle', 'wb') as f:\n",
" pickle.dump(a, f)\n",
" \n",
"del a"
]
},
{
"cell_type": "markdown",
"id": "b64088a5",
"metadata": {},
"source": [
"To reload the state of `a` from disk, we do a pickle \"load\":"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "806560ea",
"metadata": {},
"outputs": [],
"source": [
"import pickle\n",
"\n",
"with open('data.pickle', 'rb') as f:\n",
" a = pickle.load(f)\n",
" \n",
"a, a.timestamp"
]
},
{
"cell_type": "markdown",
"id": "39042681",
"metadata": {},
"source": [
"As you can see, it restored not just the Parameter values, but the timestamp (stored in the object's dictionary) as well. \n",
"\n",
"Here we are depending on the class definition of `A` actually being in memory. If we delete that definition and try to unpickle the object again, it will fail:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "67267e47",
"metadata": {},
"outputs": [],
"source": [
"del A\n",
"\n",
"with param.exceptions_summarized():\n",
" with open('data.pickle', 'rb') as f:\n",
" a = pickle.load(f)"
]
},
{
"cell_type": "markdown",
"id": "93044cbb",
"metadata": {},
"source": [
"Notice how the pickle has stored the fact that class `A` is defined in the main namespace, but because `__main__` is not an importable module, unpickling fails. Had `A` been defined in a module available for importing, unpickling would have succeeded here even if A had never previously been loaded.\n",
"\n",
"To use pickling in practice, you'll need to ensure that all functions and classes are named (not lambdas) and defined in some importable module, not just inline here in a notebook or script or command prompt. Even so, pickling can be very useful as a way to save and restore state of complex Parameterized objects."
]
},
{
"cell_type": "markdown",
"id": "3d5b6ae6",
"metadata": {},
"source": [
"### Pickling limitations and workarounds\n",
"\n",
"As you develop a module using Param, you'll need to pay attention to a few technical issues if you want to support pickling:\n",
"\n",
"1. **Callable parameter values**: If you provide any `param.Callable`, `param.Hooklist`, or other parameters that can accept callable objects to your users, you will need to warn them that none of those can be set to unnamed (lambda) functions or to one-off functions defined in the main namespace if they want to use pickling. Of course, you can accept such values during initial development when you may not care about pickling, but once things are working, move the one-off function to a proper importable module and then it will be safe to use as a picklable value. One way to make this work smoothly is to create `param.ParameterizedFunction` objects or other \"function object\" classes (classes whose instances are callable like functions but which may have state and are fully picklable); see e.g. the `numbergen` module for examples.\n",
"\n",
"2. **Skipping Parameters that should not be pickled**: In some cases, you may not _want_ the value of a given Parameter to be pickled and restored even while other state is being serialized. For instance, a Parameter whose value is set to a particular file path might cause errors if that path is restored when the pickle is loaded on a different system or once the file no longer exists. To cover such rare but potentially important cases, the Parameter can be defined with `pickle_default_value=False` (normally `True`), so that the instantaneous value is usable but won't be saved and restored with pickle.\n",
"\n",
"3. **Customizing settting and getting state**: You may find that your Parameter or Parameterized objects have other state that you need to handle specially, whether that's to save and restore data that isn't otherwise picklable, or to ignore state that should _not_ be pickled. For instance, if your object's dictionary contains some object that doesn't support pickling, then you can add code to omit that or to serialize it in some special way that allows it to be restored, e.g. by extracting a state dictionary fom it and then restoring it from the dictionary later. See the [pickle docs](https://docs.python.org/3/library/pickle.html#pickle-state) for the `__getstate__` and `__setstate__` methods that you can implement on your Parameter or Parameterized objects to override this behavior. Be sure to call `super(YourClass,self).__setstate__(state)` or the getstate equivalent so that you also store parameters and dictionary values as usual, if desired.\n",
"\n",
"4. **Loading old pickle files**: If you use pickles extensively, you may find yourself wanting to support pickle files generated by an older version of your own code, even though your code has since changed (with renamed modules, classes, or parameters, or options that are no longer supported, etc.). By default, unpickling will raise an exception if it finds information in your pickle file that does not match the current Python source code, but it is possible to add custom handling to translate old definitions to match current code, discard no-longer-used options, map from a previous approach into the current approach, etc. You can use `__getstate__` and `__setstate__` on your top-level object or on specific other classes to do just about anything like this, though it can get complicated to reason about. Best practice is to store the module version number or other suitable identifier as an attribute or Parameter on the top-level object to declare what version of the code was used to create the file, and you can then read this identifier later to determine whether you need to apply such conversions on reloading."
]
},
{
"cell_type": "markdown",
"id": "e01f6c6a",
"metadata": {},
"source": [
"## Serializing with JSON\n",
"\n",
"JSON is a human-readable string representation for nested dictionaries of key-value pairs. Compared to pickle, JSON is a much more limited representation, using a fixed set of types mapped to string values, and not natively supporting Python-specific types like tuples or custom Python objects. However, it is widely accepted across computer languages, and because it is human readable and editable and omits the detailed internal state of objects (unlike pickle), JSON works well as an interchange or configuration format.\n",
"\n",
"Param's JSON support is currently fairly limited, with support for serializing and deserializing individual (not nested) Parameterized objects. It is currently primarily used for synchronizing state \"across the wire\", e.g. between multiple apps running on different machines that communicate changes to shared state (e.g. for a remote GUI), but as proposed in [issue#520](https://github.com/holoviz/param/issues/520) it could be extended to be a general configuration and specification mechanism by adding conventions for specifying a Parameterized type for an object and its nested objects.\n",
"\n",
"To see how it currently works, let's start with a Parameterized object containing Parameters of different types:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "420c6148",
"metadata": {},
"outputs": [],
"source": [
"import param, datetime, pandas as pd\n",
"\n",
"df = pd.DataFrame({'A':[1,2,3], 'B':[1.1,2.2,3.3]})\n",
"\n",
"simple_list = [1]\n",
"\n",
"class P(param.Parameterized):\n",
" a = param.Integer(default=5, doc='Int', bounds=(2,30), inclusive_bounds=(True, False))\n",
" e = param.List([1,2,3], class_=int)\n",
" g = param.Date(default=datetime.datetime.now())\n",
" l = param.Range(default=(1.1,2.3), bounds=(1,3))\n",
" m = param.String(default='baz', allow_None=True)\n",
" s = param.DataFrame(default=df, columns=(1,4), rows=(2,5))\n",
"\n",
"p = P(a=29)\n",
"p"
]
},
{
"cell_type": "markdown",
"id": "acebf174",
"metadata": {},
"source": [
"To serialize this Parameterized object to a JSON string, call `.serialize_parameters()` on it:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "cf4ab02f",
"metadata": {},
"outputs": [],
"source": [
"s = p.param.serialize_parameters()\n",
"s"
]
},
{
"cell_type": "markdown",
"id": "ad0d7637",
"metadata": {},
"source": [
"Notice that the serialization includes not just the values set specifically on this instance (`a=29`), but also all the default values inherited from the class definition.\n",
"\n",
"You can easily select only a subset to serialize, if you wish:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "041cd4f8",
"metadata": {},
"outputs": [],
"source": [
"p.param.serialize_parameters(subset=['a','m'])"
]
},
{
"cell_type": "markdown",
"id": "d8470cef",
"metadata": {},
"source": [
"The JSON string can be saved to disk, sent via a network connection, stored in a database, or for any other usage suitable for a string.\n",
"\n",
"Once you are ready to deserialize the string into a Parameterized object, you'll need to know the class it came from (here `P`) and can then call its `deserialize_parameters` method to get parameter values to use in `P`'s constructor:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "c2644101",
"metadata": {},
"outputs": [],
"source": [
"p2 = P(**P.param.deserialize_parameters(s))\n",
"p2"
]
},
{
"cell_type": "markdown",
"id": "d59d7765",
"metadata": {},
"source": [
"As you can see, we have successfully serialized our original object `p` into a new object `p2`, which could be in a different Python process on a different machine or at a different date.\n",
"\n",
"### JSON limitations and workarounds\n",
"\n",
"To see the limitations on Param's JSON support, let's look at how it works in more detail. Because the result of serialization (`s` above) is a valid JSON string, we can use the `json` library to unpack it without any knowledge of what Parameterized class it came from:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "7ee520c9",
"metadata": {},
"outputs": [],
"source": [
"import json\n",
"dj = json.loads(s)\n",
"dj"
]
},
{
"cell_type": "markdown",
"id": "c2e54200",
"metadata": {},
"source": [
"The result is a Python dictionary of name:value pairs, some of which you can recognize as the original type (e.g. `a=29`), others that have changed type (e.g. `l=(1.1,2.3)` or `s=pd.DataFrame({'A':[1,2,3], 'B':[1.1,2.2,3.3]})`), and others that are still a string encoding of that type (e.g. `g=datetime.datetime(...)`)). If you try to pass this dictionary to your Parameterized constructor, any such value will be rejected as invalid by the corresponding Parameter:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "593c1d8b",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" P(**dj)"
]
},
{
"cell_type": "markdown",
"id": "216d6c7a",
"metadata": {},
"source": [
"That's why instead of simply `json.loads(s)`, we do `P.param.deserialize_parameters(s)`, which uses the knowledge that `P.l` is a tuple parameter to convert the resulting list `[1.1, 2.3]` into a Python tuple `(1.1, 2.3)` as required for such a parameter:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "febbc040",
"metadata": {},
"outputs": [],
"source": [
"print(dj['l'])\n",
"print(p2.l)"
]
},
{
"cell_type": "markdown",
"id": "3f410eda",
"metadata": {},
"source": [
"Similarly, parameters of type `param.Array` will unpack the list representation into a NumPy array, `param.DataFrame` unpacks the list of dicts of list into a Pandas DataFrame, etc. So, the encoding for your Parameterized object will always be standard JSON, but to _deserialize_ it fully into a Parameterized, you'll need to know the class it came from, or Param will not know that the list it finds was originally a tuple, dataframe, etc. \n",
"\n",
"For this reason, any Parameter that itself contains a Parameterized object will not be able to be JSON deserialized, since even if we knew what class it was (e.g. for `param.ClassSelector(class_=param.Number)`, it could be some subclass of that class. Because the class name is not currently stored in the JSON serialization, there is no way to restore it. Thus there is currently no support for JSON serializing or deserializing nested Parameterized objects.\n",
"\n",
"We do expect to add support for nested objects using something like the convention for datetime objects; see [issue#520](https://github.com/holoviz/param/issues/520)."
]
},
{
"cell_type": "markdown",
"id": "facde47d",
"metadata": {},
"source": [
"### JSON Schemas \n",
"\n",
"If you want to use your JSON representation in a separate process where Param is not available or perhaps in a different language altogether, Param can provide a [JSON schema](https://json-schema.org/) that specifies what type you are expecting for each Parameter. The schema for a given Parameterized can be obtained using the `schema` method:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "24afd3ee",
"metadata": {},
"outputs": [],
"source": [
"p.param.schema()"
]
},
{
"cell_type": "markdown",
"id": "d8d8e7bb",
"metadata": {},
"source": [
"Once you have the schema, you can validate that a given JSON string matches the schema, i.e. that all values included therein match the constraints listed in the schema:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0fce2ea0",
"metadata": {},
"outputs": [],
"source": [
"from jsonschema import validate\n",
"d = json.loads(s)\n",
"full_schema = {\"type\" : \"object\", \"properties\" : p.param.schema()}\n",
"validate(instance=d, schema=full_schema)"
]
},
{
"cell_type": "markdown",
"id": "4d751577",
"metadata": {},
"source": [
"If one of the parameter values fails to match the provided schema, you'll get an exception:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "612eaac6",
"metadata": {},
"outputs": [],
"source": [
"d2 = d.copy()\n",
"d2['a']='astring'\n",
"\n",
"with param.exceptions_summarized():\n",
" validate(instance=d2, schema=full_schema)"
]
},
{
"cell_type": "markdown",
"id": "163223d1",
"metadata": {},
"source": [
"The `param.schema()` call accepts the same `subset` argument as `.param.serialize_parameters()`, letting you serialize and check only a subset of the parameters if appropriate. \n",
"\n",
"You can also supply a `safe=True` argument that checks that all parameter values are _guaranteed_ to be serializable and follow the given schema. This lets you detect if there are any containers or parameters whose type is not fully specified:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9cc85749",
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized():\n",
" full2 = {\"type\" : \"object\", \"properties\" : p.param.schema(safe=True)}\n",
" validate(instance=d, schema=full2)"
]
},
{
"cell_type": "markdown",
"id": "ac593fcd",
"metadata": {},
"source": [
"## script_repr\n",
"\n",
"Parameterized objects can be constructed through a series of interactive actions, either in a GUI or command line, or as the result of automated scripts and object-construction functions. Any parameter values can also be changed at any moment once that object has been created. If you want to capture the resulting Parameterized object with any such additions and changes, you can use the `param.script_repr()` function. `script_repr` returns a representation of that object and all nested Parameterized or other supported objects as Python code that can recreate the full object later. This approach lets you go flexibly from an interactive or indirect way of creating or modifying objects, to being able to recreate that specific object again for later use. Programs with a GUI interface can use `script_repr()` as a way of exporting a runnable version of what a user created interactively in the GUI.\n",
"\n",
"For example, let's construct a Parameterized object `p` containing Parameters whose values are themselves Parameterized objects with their own Parameters:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ad5a4d3b",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class Q(param.Parameterized):\n",
" a = param.Number(39, bounds=(0,50))\n",
" b = param.String(\"str\")\n",
"\n",
"class P(param.Parameterized):\n",
" c = param.ClassSelector(default=Q(), class_=Q)\n",
" d = param.ClassSelector(default=param.Parameterized(), class_=param.Parameterized)\n",
" e = param.Range((0,1))\n",
" \n",
"q = Q(b=\"new\")\n",
"p=P(c=q, e=(2,3))\n",
"p"
]
},
{
"cell_type": "markdown",
"id": "20e238cb",
"metadata": {},
"source": [
"We can get a script representation for this object by calling `script_repr(p)`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e08e3d7b",
"metadata": {},
"outputs": [],
"source": [
"print(param.script_repr(p))"
]
},
{
"cell_type": "markdown",
"id": "ca0408d7",
"metadata": {},
"source": [
"As you can see, this representation encodes the fact that `P` was defined in the main namespace, generated inside this notebook. As you might expect, this representation has the same limitation as for `pickle` -- only classes that are in importable modules will be runnable; you'll need to save the source code to your classes in a proper Python module if you want the resulting script to be runnable. But once you have done that, you can use the `script_repr` to get a runnable version of your Parameterized object no matter how you created it, whether it was by selecting options in a GUI, adding items via a loop in a script, and so on."
]
},
{
"cell_type": "markdown",
"id": "ca55f9e2",
"metadata": {},
"source": [
"### script_repr limitations and workarounds\n",
"\n",
"Apart from making sure your functions and classes are all defined in their own importable modules, there are various considerations and limitations to keep in mind if you want to support using `script_repr`. "
]
},
{
"cell_type": "markdown",
"id": "75cdd8f5",
"metadata": {},
"source": [
"Normally, script_repr prints only parameter values that have changed from their defaults; it is designed to generate a script as close as is practical to one that a user would have typed to create the given object. If you want a record of the _complete_ set of parameter values, including all defaults, you can enable that behavior:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "57dede40",
"metadata": {},
"outputs": [],
"source": [
"import param.parameterized\n",
"param.parameterized.script_repr_suppress_defaults=True"
]
},
{
"cell_type": "markdown",
"id": "388f982f",
"metadata": {},
"source": [
"The resulting output is then suitable for archiving the full parameter state of that object, even if some default later gets changed in the source code. Note that Param is not able to detect all cases where a default value is unchanged, e.g. for Parameters with `instantiate=True`, which will always be treated as changed since each instance has a copy of that Parameter value independent of the original default value.\n",
"\n",
"You can control `script_repr` with keyword arguments:\n",
"\n",
"- `imports=[]`: If desired, a list of imports that can be built up over multiple script_repr calls to collect a full set of imports required for a script. Useful with `show_imports=False` except on the last script_repr call. Can be an empty list or a list containing some hard-coded imports needed.\n",
"- `prefix=\"\\n \"`: Optional prefix to use before a nested object.\n",
"- `qualify=True`: Whether the class's path will be included (e.g. \"a.b.C()\"), otherwise only the class will appear (\"C()\").\n",
"- `unknown_value=None`: determines what to do where a representation cannot be generated for something required to recreate the object. Such things include non-parameter positional and keyword arguments, and certain values of parameters (e.g. some random state objects). Supplying an `unknown_value` of `None` causes unrepresentable things to be silently ignored. If `unknown_value` is a string, that string will appear in place of any unrepresentable things. If `unknown_value` is `False`, an Exception will be raised if an unrepresentable value is encountered. \n",
"- `separator=\"\\n\"`: Separator to use between parameters.\n",
"- `show_imports=True`: Whether to include import statements in the output.\n",
"\n",
"\n",
"The `script_repr` behavior for a particular type, whether it's a Parameterized object or not, can be overridden to provide any functionality needed. Such overrides are stored in `param.parameterized.script_repr_reg`, which already contains handling for list and tuple containers, various objects with random state, functions, and modules. See examples in \n",
"`param.parameterized`."
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/user_guide/Simplifying_Codebases.ipynb 0000664 0000000 0000000 00000035146 14636363363 0023046 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Simplifying Codebases\n",
"\n",
"Param's just a Python library, and so anything you can do with Param you can do \"manually\". So, why use Param?\n",
"\n",
"The most immediate benefit to using Param is that it allows you to greatly simplify your codebases, making them much more clear, readable, and maintainable, while simultaneously providing robust handling against error conditions.\n",
"\n",
"Param does this by letting a programmer explicitly declare the types and values of parameters accepted by the code. Param then ensures that only suitable values of those parameters ever make it through to the underlying code, removing the need to handle any of those conditions explicitly.\n",
"\n",
"To see how this works, let's create a Python class with some attributes without using Param:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"class OrdinaryClass(object):\n",
" def __init__(self, a=2, b=3, title=\"sum\"):\n",
" self.a = a\n",
" self.b = b\n",
" self.title = title\n",
" \n",
" def __call__(self):\n",
" return self.title + \": \" + str(self.a + self.b)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As this is just standard Python, we can of course instantiate this class, modify its variables, and call it:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"o1 = OrdinaryClass(b=4, title=\"Sum\")\n",
"o1.a=4\n",
"o1()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The same code written using Param would look like:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"import param\n",
" \n",
"class ParamClass(param.Parameterized):\n",
" a = param.Integer(2, bounds=(0,1000), doc=\"First addend\")\n",
" b = param.Integer(3, bounds=(0,1000), doc=\"Second addend\")\n",
" title = param.String(default=\"sum\", doc=\"Title for the result\")\n",
" \n",
" def __call__(self):\n",
" return self.title + \": \" + str(self.a + self.b)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"o2 = ParamClass(b=4, title=\"Sum\")\n",
"o2()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"As you can see, the Parameters here are used precisely like normal attributes once they are defined, so the code for `__call__` and for invoking the constructor are the same in both cases. It's thus generally quite straightforward to migrate an existing class into Param. So, why do that?\n",
"\n",
"Well, with fewer lines of code than the ordinary class, you've now unlocked a whole wealth of features and better behavior! For instance, what happens if a user tries to supply some inappropriate data? With Param, such errors will be caught immediately:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized(): \n",
" o3 = ParamClass()\n",
" o3.b = -5"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Of course, you could always add more code to an ordinary Python class to check for errors like that, but it quickly gets unwieldy:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"class OrdinaryClass2(object):\n",
" def __init__(self, a=2, b=3, title=\"sum\"):\n",
" if type(a) is not int:\n",
" raise ValueError(\"'a' must be an integer\")\n",
" if type(b) is not int:\n",
" raise ValueError(\"'b' must be an integer\")\n",
" if a<0:\n",
" raise ValueError(\"'a' must be at least `0`\")\n",
" if b<0:\n",
" raise ValueError(\"'b' must be at least `0`\")\n",
" if type(title) is not str:\n",
" raise ValueError(\"'title' must be a string\") \n",
" \n",
" self.a = a\n",
" self.b = b\n",
" self.title = title\n",
" \n",
" def __call__(self):\n",
" return self.title + \": \" + str(self.a + self.b)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized(): \n",
" OrdinaryClass2(a=\"f\")"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Unfortunately, catching errors in the constructor like that won't help if someone modifies the attribute directly, which won't be detected as an error:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"o4 = OrdinaryClass2()\n",
"o4.a = \"four\""
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Python will happily accept this incorrect value and will continue processing. It may only be much later, in a very different part of your code, that you see a mysterious error message that's then very difficult to relate back to the actual problem you need to fix:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized(): \n",
" o4()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Here there's no problem with the code in the cell above; `o4()` is fully valid Python; the real problem is in the preceding cell, which could have been in a completely different file or library. The error message is also obscure and confusing at this level, because the user of `o4` may have no idea why strings and integers are getting concatenated.\n",
"\n",
"To get a better error message, you _could_ move those checks into the `__call__` method, which would make sure that errors are always eventually detected:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"class OrdinaryClass3(object):\n",
" def __init__(self, a=2, b=3, title=\"sum\"): \n",
" self.a = a\n",
" self.b = b\n",
" self.title = title\n",
" \n",
" def __call__(self):\n",
" if type(self.a) is not int:\n",
" raise ValueError(\"'a' must be an integer\")\n",
" if type(self.b) is not int:\n",
" raise ValueError(\"'b' must be an integer\")\n",
" if self.a<0:\n",
" raise ValueError(\"'a' must be at least `0`\")\n",
" if self.b<0:\n",
" raise ValueError(\"'b' must be at least `0`\")\n",
" if type(self.title) is not str:\n",
" raise ValueError(\"'title' must be a string\") \n",
"\n",
" return self.title + \": \" + str(self.a + self.b)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"o5 = OrdinaryClass3()\n",
"o5.a = \"four\""
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized(): \n",
" o5()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"But you'd now have to check for errors in _every_ _single_ _method_ that might use those parameters. Worse, you still only detect the problem very late, far from where it was first introduced. Any distance between the error and the error report makes it much more difficult to address, as the user then has to track down where in the code `a` might have gotten set to a non-integer.\n",
"\n",
"With Param you can catch such problems at their start, as soon as an incorrect value is provided, when it is still simple to detect and correct it. To get those same features in hand-written Python code, you would need to provide explicit getters and setters, which is made easier with Python properties and decorators, but is still quite unwieldy:"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"class OrdinaryClass4(object):\n",
" def __init__(self, a=2, b=3, title=\"sum\"):\n",
" self.a = a\n",
" self.b = b\n",
" self.title = title\n",
" \n",
" @property\n",
" def a(self): return self.__a\n",
" @a.setter\n",
" def a(self, a):\n",
" if type(a) is not int:\n",
" raise ValueError(\"'a' must be an integer\")\n",
" if a < 0:\n",
" raise ValueError(\"'a' must be at least `0`\")\n",
" self.__a = a\n",
" \n",
" @property\n",
" def b(self): return self.__b\n",
" @b.setter\n",
" def b(self, b):\n",
" if type(b) is not int:\n",
" raise ValueError(\"'a' must be an integer\")\n",
" if b < 0:\n",
" raise ValueError(\"'a' must be at least `0`\")\n",
" self.__b = b\n",
"\n",
" @property\n",
" def title(self): return self.__title\n",
" def title(self, b):\n",
" if type(title) is not string:\n",
" raise ValueError(\"'title' must be a string\")\n",
" self.__title = title\n",
"\n",
" def __call__(self):\n",
" return self.title + \": \" + str(self.a + self.b)"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"o5=OrdinaryClass4()\n",
"o5()"
]
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {},
"outputs": [],
"source": [
"with param.exceptions_summarized(): \n",
" o5=OrdinaryClass4()\n",
" o5.b=-6"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Note that this code has an easily overlooked mistake in it, reporting `a` rather than `b` as the problem. This sort of error is extremely common in copy-pasted validation code of this type, because tests rarely exercise all of the error conditions involved.\n",
"\n",
"As you can see, even getting close to the automatic validation already provided by Param requires 8 methods and >30 highly repetitive lines of code, even when using relatively esoteric Python features like properties and decorators, and still doesn't yet implement other Param features like automatic documentation, attribute inheritance, or dynamic values. With Param, the corresponding `ParamClass` code only requires 6 lines and no fancy techniques beyond Python classes. Most importantly, the Param version lets readers and program authors focus directly on what this code actually does, which is to compute a function from three provided parameters:\n",
"\n",
"```\n",
"class ParamClass(param.Parameterized):\n",
" a = param.Integer(2, bounds=(0,1000), doc=\"First addend\")\n",
" b = param.Integer(3, bounds=(0,1000), doc=\"Second addend\")\n",
" title = param.String(default=\"sum\", doc=\"Title for the result\")\n",
" \n",
" def __call__(self):\n",
" return self.title + \": \" + str(self.a + self.b)\n",
"```\n",
"\n",
"Even a quick skim of this code reveals what parameters are available, what values they will accept, what the default values are, and how those parameters will be used in the method. Plus the actual code of the method stands out immediately, as all the code is either parameters or actual functionality. In contrast, users of OrdinaryClass3 will have to read through dozens of lines of code to discern even basic information about usage, or else authors of the code will need to create and maintain docstrings that may or may not match the actual code over time and will further increase the amount of text to write and maintain."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Programming contracts\n",
"\n",
"If you think about the examples above, you can see how Param makes it simple for programmers to make a contract with their users, being explicit and clear what will be accepted and rejected, while also allowing programmers to make safe assumptions about what inputs the code may ever receive. There is no need for `__call__` _ever_ to check for the type of one of its parameters, whether it's in the range allowed, or any other property that can be enforced by Param. Your custom code can then be much more linear and straightforward, getting right to work with the actual task at hand, without having to have reams of `if` statements and `asserts()` that disrupt the flow of the source file and make the reader get sidetracked in error-handling code. Param lets you once and for all declare what this code accepts, which is both clear documentation to the user and a guarantee that the programmer can forget about any other possible value a user might someday supply.\n",
"\n",
"Crucially, these contracts apply not just between the user and a given piece of code, but also between components of the system itself. When validation code is expensive, as in ordinary Python, programmers will typically do it only at the edges of the system, where input from the user is accepted. But expressing types and ranges is so easy in Param, it can be done for any major component in the system. The Parameter list declares very clearly what that component accepts, which lets the code for that component ignore all potential inputs that are disallowed by the Parameter specifications, while correctly advertising to the rest of the codebase what inputs are allowed. Programmers can thus focus on their particular components of interest, knowing precisely what inputs will ever be let through, without having to reason about the flow of configuration and data throughout the whole system.\n",
"\n",
"Without Param, you should expect Python code to be full of confusing error checking and handling of different input types, while still only catching a small fraction of the possible incorrect inputs that could be provided. But Param-based code should be dramatically easier to read, easier to maintain, easier to develop, and nearly bulletproof against mistaken or even malicious usage. "
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 4
}
param-2.1.1/doc/user_guide/index.md 0000664 0000000 0000000 00000004521 14636363363 0017163 0 ustar 00root root 0000000 0000000 # User Guide
This user guide provides detailed information about how to use Param, assuming you have worked through the Getting Started guide.
- [Simplifying Codebases](./Simplifying_Codebases): How Param allows you to eliminate boilerplate and unsafe code
- [Parameters](./Parameters): Using parameters (Class vs. instance parameters, setting defaults, etc.)
- [Parameter Types](./Parameter_Types): Predefined Parameter classes available for your use
- [Dependencies and Watchers](./Dependencies_and_Watchers): Expressing relationships between parameters and parameters or code, and triggering events.
- [References](./References): Allowing parameters to resolve references to other parameters, reactive expressions, functions and generators.
- [Reactive Expressions](./Reactive_Expressions): How to write expressions and functions that automatically re-evaluate when their parameter inputs change.
- [Generators](./Generators): Using (asynchronous) generators to drive events on parameters and expressions in a "push" based model.
- [Serialization and Persistence](./Serialization_and_Persistence): Saving the state of a Parameterized object to a text, script, or pickle file
- [Outputs](./Outputs): Output types and connecting output to Parameter inputs
- [Logging and Warnings](./Logging_and_Warnings): Logging, messaging, warning, and raising errors on Parameterized objects
- [ParameterizedFunctions](./ParameterizedFunctions): Parameterized function objects, for configurable callables
- [Dynamic Parameters](./Dynamic_Parameters): Using dynamic parameter values with and without Numbergen
- [How Param Works](./How_Param_Works): Internal details, for Param developers and power users
- [Using Param in GUIs](https://panel.holoviz.org/how_to/param/index.html): (external site) Using Param with Panel to make GUIs
```{toctree}
---
hidden: true
maxdepth: 2
---
Overview
Simplifying Codebases
Parameters
Parameter Types
Dependencies and Watchers
References
Reactive Expressions
Generators
Serialization and Persistence
Outputs
Logging and Warnings
ParameterizedFunctions
Dynamic Parameters
How Param Works
```
param-2.1.1/numbergen/ 0000775 0000000 0000000 00000000000 14636363363 0014612 5 ustar 00root root 0000000 0000000 param-2.1.1/numbergen/__init__.py 0000664 0000000 0000000 00000066446 14636363363 0016743 0 ustar 00root root 0000000 0000000 """
Callable objects that generate numbers according to different distributions.
"""
import random
import operator
import hashlib
import struct
import fractions
from ctypes import c_size_t
from math import e,pi
import param
from param import __version__ # noqa: API import
class TimeAware(param.Parameterized):
"""
Class of objects that have access to a global time function
and have the option of using it to generate time-dependent values
as necessary.
In the simplest case, an object could act as a strict function of
time, returning the current time transformed according to a fixed
equation. Other objects may support locking their results to a
timebase, but also work without time. For instance, objects with
random state could return a new random value for every call, with
no notion of time, or could always return the same value until the
global time changes. Subclasses should thus provide an ability to
return a time-dependent value, but may not always do so.
"""
time_dependent = param.Boolean(default=False, doc="""
Whether the given time_fn should be used to constrain the
results generated.""")
time_fn = param.Callable(default=param.Dynamic.time_fn, doc="""
Callable used to specify the time that determines the state
and return value of the object, if time_dependent=True.""")
def __init__(self, **params):
super().__init__(**params)
self._check_time_fn()
def _check_time_fn(self, time_instance=False):
"""
If time_fn is the global time function supplied by
param.Dynamic.time_fn, make sure Dynamic parameters are using
this time function to control their behaviour.
If time_instance is True, time_fn must be a param.Time instance.
"""
if time_instance and not isinstance(self.time_fn, param.Time):
raise AssertionError("%s requires a Time object"
% self.__class__.__name__)
if self.time_dependent:
global_timefn = self.time_fn is param.Dynamic.time_fn
if global_timefn and not param.Dynamic.time_dependent:
raise AssertionError("Cannot use Dynamic.time_fn as"
" parameters are ignoring time.")
class TimeDependent(TimeAware):
"""
Objects that have access to a time function that determines the
output value. As a function of time, this type of object should
allow time values to be randomly jumped forwards or backwards,
but for a given time point, the results should remain constant.
The time_fn must be an instance of param.Time, to ensure all the
facilities necessary for safely navigating the timeline are
available.
"""
time_dependent = param.Boolean(default=True, readonly=True, doc="""
Read-only parameter that is always True.""")
def _check_time_fn(self):
super()._check_time_fn(time_instance=True)
class NumberGenerator(param.Parameterized):
"""
Abstract base class for any object that when called produces a number.
Primarily provides support for using NumberGenerators in simple
arithmetic expressions, such as abs((x+y)/z), where x,y,z are
NumberGenerators or numbers.
"""
def __call__(self):
raise NotImplementedError
# Could define any of Python's operators here, esp. if they have operator or ufunc equivalents
def __add__ (self,operand): return BinaryOperator(self,operand,operator.add)
def __sub__ (self,operand): return BinaryOperator(self,operand,operator.sub)
def __mul__ (self,operand): return BinaryOperator(self,operand,operator.mul)
def __mod__ (self,operand): return BinaryOperator(self,operand,operator.mod)
def __pow__ (self,operand): return BinaryOperator(self,operand,operator.pow)
def __div__ (self,operand): return BinaryOperator(self,operand,operator.div)
def __truediv__ (self,operand): return BinaryOperator(self,operand,operator.truediv)
def __floordiv__ (self,operand): return BinaryOperator(self,operand,operator.floordiv)
def __radd__ (self,operand): return BinaryOperator(self,operand,operator.add,True)
def __rsub__ (self,operand): return BinaryOperator(self,operand,operator.sub,True)
def __rmul__ (self,operand): return BinaryOperator(self,operand,operator.mul,True)
def __rmod__ (self,operand): return BinaryOperator(self,operand,operator.mod,True)
def __rpow__ (self,operand): return BinaryOperator(self,operand,operator.pow,True)
def __rdiv__ (self,operand): return BinaryOperator(self,operand,operator.div,True)
def __rtruediv__ (self,operand): return BinaryOperator(self,operand,operator.truediv,True)
def __rfloordiv__(self,operand): return BinaryOperator(self,operand,operator.floordiv,True)
def __neg__ (self): return UnaryOperator(self,operator.neg)
def __pos__ (self): return UnaryOperator(self,operator.pos)
def __abs__ (self): return UnaryOperator(self,operator.abs)
operator_symbols = {
operator.add:'+',
operator.sub:'-',
operator.mul:'*',
operator.mod:'%',
operator.pow:'**',
operator.truediv:'/',
operator.floordiv:'//',
operator.neg:'-',
operator.pos:'+',
operator.abs:'abs',
}
def pprint(x, *args, **kwargs):
"Pretty-print the provided item, translating operators to their symbols"
return x.pprint(*args, **kwargs) if hasattr(x,'pprint') else operator_symbols.get(x, repr(x))
class BinaryOperator(NumberGenerator):
"""Applies any binary operator to NumberGenerators or numbers to yield a NumberGenerator."""
def __init__(self,lhs,rhs,operator,reverse=False,**args):
"""
Accepts two NumberGenerator operands, an operator, and
optional arguments to be provided to the operator when calling
it on the two operands.
"""
# Note that it's currently not possible to set
# parameters in the superclass when creating an instance,
# because **args is used by this class itself.
super().__init__()
if reverse:
self.lhs=rhs
self.rhs=lhs
else:
self.lhs=lhs
self.rhs=rhs
self.operator=operator
self.args=args
def __call__(self):
return self.operator(self.lhs() if callable(self.lhs) else self.lhs,
self.rhs() if callable(self.rhs) else self.rhs, **self.args)
def pprint(self, *args, **kwargs):
return (pprint(self.lhs, *args, **kwargs) +
pprint(self.operator, *args, **kwargs) +
pprint(self.rhs, *args, **kwargs))
class UnaryOperator(NumberGenerator):
"""Applies any unary operator to a NumberGenerator to yield another NumberGenerator."""
def __init__(self,operand,operator,**args):
"""
Accepts a NumberGenerator operand, an operator, and
optional arguments to be provided to the operator when calling
it on the operand.
"""
# Note that it's currently not possible to set
# parameters in the superclass when creating an instance,
# because **args is used by this class itself.
super().__init__()
self.operand=operand
self.operator=operator
self.args=args
def __call__(self):
return self.operator(self.operand(),**self.args)
def pprint(self, *args, **kwargs):
return (pprint(self.operator, *args, **kwargs) + '(' +
pprint(self.operand, *args, **kwargs) + ')')
class Hash:
"""
A platform- and architecture-independent hash function (unlike
Python's inbuilt hash function) for use with an ordered collection
of rationals or integers.
The supplied name sets the initial hash state. The output from
each call is a 32-bit integer to ensure the value is a regular
Python integer (and not a Python long) on both 32-bit and 64-bit
platforms. This can be important to seed Numpy's random number
generator safely (a bad Numpy bug!).
The number of inputs (integer or rational numbers) to be supplied
for __call__ must be specified in the constructor and must stay
constant across calls.
"""
def __init__(self, name, input_count):
self.name = name
self.input_count = input_count
self._digest = hashlib.md5()
self._digest.update(name.encode())
self._hash_struct = struct.Struct( "!" +" ".join(["I"] * (input_count * 2)))
def _rational(self, val):
"""Convert the given value to a rational, if necessary."""
I32 = 4294967296 # Maximum 32 bit unsigned int (i.e. 'I') value
if isinstance(val, int):
numer, denom = val, 1
elif isinstance(val, fractions.Fraction):
numer, denom = val.numerator, val.denominator
elif hasattr(val, 'numer'):
(numer, denom) = (int(val.numer()), int(val.denom()))
else:
param.main.param.log(param.WARNING, "Casting type '%s' to Fraction.fraction"
% type(val).__name__)
frac = fractions.Fraction(str(val))
numer, denom = frac.numerator, frac.denominator
return numer % I32, denom % I32
def __getstate__(self):
"""
Avoid Hashlib.md5 TypeError in deepcopy (hashlib issue)
"""
d = self.__dict__.copy()
d.pop('_digest')
d.pop('_hash_struct')
return d
def __setstate__(self, d):
self._digest = hashlib.md5()
name, input_count = d['name'], d['input_count']
self._digest.update(name.encode())
self._hash_struct = struct.Struct( "!" +" ".join(["I"] * (input_count * 2)))
self.__dict__.update(d)
def __call__(self, *vals):
"""
Given integer or rational inputs, generate a cross-platform,
architecture-independent 32-bit integer hash.
"""
# Convert inputs to (numer, denom) pairs with integers
# becoming (int, 1) pairs to match gmpy.mpqs for int values.
pairs = [self._rational(val) for val in vals]
# Unpack pairs and fill struct with ints to update md5 hash
ints = [el for pair in pairs for el in pair]
digest = self._digest.copy()
digest.update(self._hash_struct.pack(*ints))
# Convert from hex string to 32 bit int
return int(digest.hexdigest()[:7], 16)
class TimeAwareRandomState(TimeAware):
"""
Generic base class to enable time-dependent random
streams. Although this class is the basis of all random numbergen
classes, it is designed to be useful whenever time-dependent
randomness is needed using param's notion of time. For instance,
this class is used by the imagen package to define time-dependent,
random distributions over 2D arrays.
For generality, this class may use either the Random class from
Python's random module or numpy.random.RandomState. Either of
these random state objects may be used to generate numbers from
any of several different random distributions (e.g. uniform,
Gaussian). The latter offers the ability to generate
multi-dimensional random arrays and more random distributions but
requires numpy as a dependency.
If declared time_dependent, the random state is fully determined
by a hash value per call. The hash is initialized once with the
object name and then per call using a tuple consisting of the time
(via time_fn) and the global param.random_seed. As a consequence,
for a given name and fixed value of param.random_seed, the random
values generated will be a fixed function of time.
If the object name has not been set and time_dependent is True, a
message is generated warning that the default object name is
dependent on the order of instantiation. To ensure that the
random number stream will remain constant even if other objects
are added or reordered in your file, supply a unique name
explicitly when you construct the RandomDistribution object.
"""
# Historically, the default random state was seeded with the tuple
# (500, 500). The CPython implementation implicitly formed an unsigned
# integer seed using the hash of the tuple as in the expression below. Note
# that the resulting integer, and therefore the default initial random
# state, varies across CPython versions (as the hash algorithm has changed)
# and also between 32-bit and 64-bit interpreters.
#
# Seeding based on hashing is deprecated since Python 3.9 and removed in
# Python 3.11; we explicitly continue the historical behavior for the time
# being.
random_generator = param.Parameter(
default=random.Random(c_size_t(hash((500,500))).value), doc=
"""
Random state used by the object. This may be an instance
of random.Random from the Python standard library or an
instance of numpy.random.RandomState.
This random state may be exclusively owned by the object or
may be shared by all instance of the same class. It is always
possible to give an object its own unique random state by
setting this parameter with a new random state instance.
""")
__abstract = True
def _initialize_random_state(self, seed=None, shared=True, name=None):
"""
Initialization method to be called in the constructor of
subclasses to initialize the random state correctly.
If seed is None, there is no control over the random stream
(no reproducibility of the stream).
If shared is True (and not time-dependent), the random state
is shared across all objects of the given class. This can be
overridden per object by creating new random state to assign
to the random_generator parameter.
"""
if seed is None: # Equivalent to an uncontrolled seed.
seed = random.Random().randint(0, 1000000)
suffix = ''
else:
suffix = str(seed)
# If time_dependent, independent state required: otherwise
# time-dependent seeding (via hash) will affect shared
# state. Note that if all objects have time_dependent=True
# shared random state is safe and more memory efficient.
if self.time_dependent or not shared:
self.random_generator = type(self.random_generator)(seed)
# Seed appropriately (if not shared)
if not shared:
self.random_generator.seed(seed)
if name is None:
self._verify_constrained_hash()
hash_name = name if name else self.name
if not shared: hash_name += suffix
self._hashfn = Hash(hash_name, input_count=2)
if self.time_dependent:
self._hash_and_seed()
def _verify_constrained_hash(self):
"""
Warn if the object name is not explicitly set.
"""
changed_params = self.param.values(onlychanged=True)
if self.time_dependent and ('name' not in changed_params):
self.param.log(param.WARNING, "Default object name used to set the seed: "
"random values conditional on object instantiation order.")
def _hash_and_seed(self):
"""
To be called between blocks of random number generation. A
'block' can be an unbounded sequence of random numbers so long
as the time value (as returned by time_fn) is guaranteed not
to change within the block. If this condition holds, each
block of random numbers is time-dependent.
Note: param.random_seed is assumed to be integer or rational.
"""
hashval = self._hashfn(self.time_fn(), param.random_seed)
self.random_generator.seed(hashval)
class RandomDistribution(NumberGenerator, TimeAwareRandomState):
"""
The base class for all Numbergenerators using random state.
Numbergen provides a hierarchy of classes to make it easier to use
the random distributions made available in Python's random module,
where each class is tied to a particular random distribution.
RandomDistributions support setting parameters on creation rather
than passing them each call, and allow pickling to work properly.
Code that uses these classes will be independent of how many
parameters are used by the underlying distribution, and can simply
treat them as a generic source of random numbers.
RandomDistributions are examples of TimeAwareRandomState, and thus
can be locked to a global time if desired. By default,
time_dependent=False, and so a new random value will be generated
each time these objects are called. If you have a global time
function, you can set time_dependent=True, so that the random
values will instead be constant at any given time, changing only
when the time changes. Using time_dependent values can help you
obtain fully reproducible streams of random numbers, even if you
e.g. move time forwards and backwards for testing.
Note: Each RandomDistribution object has independent random state.
"""
seed = param.Integer(default=None, allow_None=True, doc="""
Sets the seed of the random number generator and can be used to
randomize time dependent streams.
If seed is None, there is no control over the random stream
(i.e. no reproducibility of the stream).""")
__abstract = True
def __init__(self,**params):
"""
Initialize a new Random() instance and store the supplied
positional and keyword arguments.
If seed=X is specified, sets the Random() instance's seed.
Otherwise, calls creates an unseeded Random instance which is
likely to result in a state very different from any just used.
"""
super().__init__(**params)
self._initialize_random_state(seed=self.seed, shared=False)
def __call__(self):
if self.time_dependent:
self._hash_and_seed()
class UniformRandom(RandomDistribution):
"""
Specified with lbound and ubound; when called, return a random
number in the range [lbound, ubound).
See the random module for further details.
"""
lbound = param.Number(default=0.0,doc="Inclusive lower bound.")
ubound = param.Number(default=1.0,doc="Exclusive upper bound.")
def __call__(self):
super().__call__()
return self.random_generator.uniform(self.lbound,self.ubound)
class UniformRandomOffset(RandomDistribution):
"""
Identical to UniformRandom, but specified by mean and range.
When called, return a random number in the range
[mean - range/2, mean + range/2).
See the random module for further details.
"""
mean = param.Number(default=0.0, doc="""Mean value""")
range = param.Number(default=1.0, bounds=(0.0,None), doc="""
Difference of maximum and minimum value""")
def __call__(self):
super().__call__()
return self.random_generator.uniform(
self.mean - self.range / 2.0,
self.mean + self.range / 2.0)
class UniformRandomInt(RandomDistribution):
"""
Specified with lbound and ubound; when called, return a random
number in the inclusive range [lbound, ubound].
See the randint function in the random module for further details.
"""
lbound = param.Number(default=0,doc="Inclusive lower bound.")
ubound = param.Number(default=1000,doc="Inclusive upper bound.")
def __call__(self):
super().__call__()
x = self.random_generator.randint(self.lbound,self.ubound)
return x
class Choice(RandomDistribution):
"""
Return a random element from the specified list of choices.
Accepts items of any type, though they are typically numbers.
See the choice() function in the random module for further details.
"""
choices = param.List(default=[0,1],
doc="List of items from which to select.")
def __call__(self):
super().__call__()
return self.random_generator.choice(self.choices)
class NormalRandom(RandomDistribution):
"""
Normally distributed (Gaussian) random number.
Specified with mean mu and standard deviation sigma.
See the random module for further details.
"""
mu = param.Number(default=0.0,doc="Mean value.")
sigma = param.Number(default=1.0,bounds=(0.0,None),doc="Standard deviation.")
def __call__(self):
super().__call__()
return self.random_generator.normalvariate(self.mu,self.sigma)
class VonMisesRandom(RandomDistribution):
"""
Circularly normal distributed random number.
If kappa is zero, this distribution reduces to a uniform random
angle over the range 0 to 2*pi. Otherwise, it is concentrated to
a greater or lesser degree (determined by kappa) around the mean
mu. For large kappa (narrow peaks), this distribution approaches
the Gaussian (normal) distribution with variance 1/kappa. See the
random module for further details.
"""
mu = param.Number(default=0.0,softbounds=(0.0,2*pi),doc="""
Mean value, typically in the range 0 to 2*pi.""")
kappa = param.Number(default=1.0,bounds=(0.0,None),softbounds=(0.0,50.0),doc="""
Concentration (inverse variance).""")
def __call__(self):
super().__call__()
return self.random_generator.vonmisesvariate(self.mu,self.kappa)
class ScaledTime(NumberGenerator, TimeDependent):
"""
The current time multiplied by some conversion factor.
"""
factor = param.Number(default=1.0, doc="""
The factor to be multiplied by the current time value.""")
def __call__(self):
return float(self.time_fn() * self.factor)
class BoxCar(NumberGenerator, TimeDependent):
"""
The boxcar function over the specified time interval. The bounds
are exclusive: zero is returned at the onset time and at the
offset (onset+duration).
If duration is None, then this reduces to a step function around the
onset value with no offset.
See http://en.wikipedia.org/wiki/Boxcar_function
"""
onset = param.Number(0.0, doc="Time of onset.")
duration = param.Number(None, allow_None=True, bounds=(0.0,None), doc="""
Duration of step value.""")
def __call__(self):
if self.time_fn() <= self.onset:
return 0.0
elif (self.duration is not None) and (self.time_fn() > self.onset + self.duration):
return 0.0
else:
return 1.0
class SquareWave(NumberGenerator, TimeDependent):
"""
Generate a square wave with 'on' periods returning 1.0 and
'off'periods returning 0.0 of specified duration(s). By default
the portion of time spent in the high state matches the time spent
in the low state (a duty cycle of 50%), but the duty cycle can be
controlled if desired.
The 'on' state begins after a time specified by the 'onset'
parameter. The onset duration supplied must be less than the off
duration.
"""
onset = param.Number(0.0, doc="""Time of onset of the first 'on'
state relative to time 0. Must be set to a value less than the
'off_duration' parameter.""")
duration = param.Number(1.0, allow_None=False, bounds=(0.0,None), doc="""
Duration of the 'on' state during which a value of 1.0 is
returned.""")
off_duration = param.Number(default=None, allow_None=True,
bounds=(0.0,None), doc="""
Duration of the 'off' value state during which a value of 0.0
is returned. By default, this duration matches the value of
the 'duration' parameter.""")
def __init__(self, **params):
super().__init__(**params)
if self.off_duration is None:
self.off_duration = self.duration
if self.onset > self.off_duration:
raise AssertionError("Onset value needs to be less than %s" % self.onset)
def __call__(self):
phase_offset = (self.time_fn() - self.onset) % (self.duration + self.off_duration)
if phase_offset < self.duration:
return 1.0
else:
return 0.0
class ExponentialDecay(NumberGenerator, TimeDependent):
"""
Function object that provides a value that decays according to an
exponential function, based on a given time function.
Returns starting_value*base^(-time/time_constant).
See http://en.wikipedia.org/wiki/Exponential_decay.
"""
starting_value = param.Number(1.0, doc="Value used for time zero.")
ending_value = param.Number(0.0, doc="Value used for time infinity.")
time_constant = param.Number(10000,doc="""
Time scale for the exponential; large values give slow decay.""")
base = param.Number(e, doc="""
Base of the exponent; the default yields starting_value*exp(-t/time_constant).
Another popular choice of base is 2, which allows the
time_constant to be interpreted as a half-life.""")
def __call__(self):
Vi = self.starting_value
Vm = self.ending_value
exp = -1.0*float(self.time_fn())/float(self.time_constant)
return Vm + (Vi - Vm) * self.base**exp
class TimeSampledFn(NumberGenerator, TimeDependent):
"""
Samples the values supplied by a time_dependent callable at
regular intervals of duration 'period', with the sampled value
held constant within each interval.
"""
period = param.Number(default=1.0, bounds=(0.0,None),
inclusive_bounds=(False,True), softbounds=(0.0,5.0), doc="""
The periodicity with which the values of fn are sampled.""")
offset = param.Number(default=0.0, bounds=(0.0,None),
softbounds=(0.0,5.0), doc="""
The offset from time 0.0 at which the first sample will be drawn.
Must be less than the value of period.""")
fn = param.Callable(doc="""
The time-dependent function used to generate the sampled values.""")
def __init__(self, **params):
super().__init__(**params)
if not getattr(self.fn,'time_dependent', False):
raise Exception("The function 'fn' needs to be time dependent.")
if self.time_fn != self.fn.time_fn:
raise Exception("Objects do not share the same time_fn")
if self.offset >= self.period:
raise Exception("The onset value must be less than the period.")
def __call__(self):
current_time = self.time_fn()
current_time += self.offset
difference = current_time % self.period
with self.time_fn as t:
t(current_time - difference - self.offset)
value = self.fn()
return value
class BoundedNumber(NumberGenerator):
"""
Function object that silently enforces numeric bounds on values
returned by a callable object.
"""
generator = param.Callable(None, doc="Object to call to generate values.")
bounds = param.Parameter((None,None), doc="""
Legal range for the value returned, as a pair.
The default bounds are (None,None), meaning there are actually
no bounds. One or both bounds can be set by specifying a
value. For instance, bounds=(None,10) means there is no lower
bound, and an upper bound of 10.""")
def __call__(self):
val = self.generator()
min_, max_ = self.bounds
if min_ is not None and val < min_: return min_
elif max_ is not None and val > max_: return max_
else: return val
_public = list({_k for _k,_v in locals().items() if isinstance(_v,type) and issubclass(_v,NumberGenerator)})
__all__ = _public
param-2.1.1/param/ 0000775 0000000 0000000 00000000000 14636363363 0013730 5 ustar 00root root 0000000 0000000 param-2.1.1/param/__init__.py 0000664 0000000 0000000 00000011665 14636363363 0016052 0 ustar 00root root 0000000 0000000 import os
from . import version # noqa: api import
from .depends import depends # noqa: api import
from .parameterized import ( # noqa: api import
Parameterized, Parameter, Skip, String, ParameterizedFunction,
ParamOverrides, Undefined, get_logger
)
from .parameterized import (batch_watch, output, script_repr, # noqa: api import
discard_events, edit_constant)
from .parameterized import shared_parameters # noqa: api import
from .parameterized import logging_level # noqa: api import
from .parameterized import DEBUG, VERBOSE, INFO, WARNING, ERROR, CRITICAL # noqa: api import
from .parameters import ( # noqa: api import
guess_param_types,
param_union,
parameterized_class,
guess_bounds,
get_soft_bounds,
resolve_path,
normalize_path,
Time,
Infinity,
Dynamic,
Bytes,
Number,
Integer,
Magnitude,
Boolean,
Tuple,
NumericTuple,
XYCoordinates,
Callable,
Action,
Composite,
SelectorBase,
ListProxy,
Selector,
ObjectSelector,
ClassSelector,
List,
HookList,
Dict,
Array,
DataFrame,
Series,
Path,
Filename,
Foldername,
FileSelector,
ListSelector,
MultiFileSelector,
Date,
CalendarDate,
Color,
Range,
DateRange,
CalendarDateRange,
Event,
)
from .reactive import bind, rx # noqa: api import
from ._utils import ( # noqa: api import
produce_value,
as_unicode,
is_ordered_dict,
hashable,
named_objs,
descendents,
concrete_descendents,
abbreviate_paths,
exceptions_summarized,
_is_number,
)
# Define '__version__'
try:
# For performance reasons on imports, avoid importing setuptools_scm
# if not in a .git folder
if os.path.exists(os.path.join(os.path.dirname(__file__), "..", ".git")):
# If setuptools_scm is installed (e.g. in a development environment with
# an editable install), then use it to determine the version dynamically.
from setuptools_scm import get_version
# This will fail with LookupError if the package is not installed in
# editable mode or if Git is not installed.
__version__ = get_version(root="..", relative_to=__file__)
else:
raise FileNotFoundError
except (ImportError, LookupError, FileNotFoundError):
# As a fallback, use the version that is hard-coded in the file.
try:
# __version__ was added in _version in setuptools-scm 7.0.0, we rely on
# the hopefully stable version variable.
from ._version import version as __version__
except (ModuleNotFoundError, ImportError):
# Either _version doesn't exist (ModuleNotFoundError) or version isn't
# in _version (ImportError). ModuleNotFoundError is a subclass of
# ImportError, let's be explicit anyway.
# Try something else:
from importlib.metadata import version as mversion, PackageNotFoundError
try:
__version__ = mversion("param")
except PackageNotFoundError:
# The user is probably trying to run this without having installed
# the package.
__version__ = "0.0.0+unknown"
#: Top-level object to allow messaging not tied to a particular
#: Parameterized object, as in 'param.main.warning("Invalid option")'.
main=Parameterized(name="main")
# A global random seed (integer or rational) available for controlling
# the behaviour of Parameterized objects with random state.
random_seed = 42
__all__ = (
'Action',
'Array',
'Boolean',
'Bytes',
'CRITICAL',
'CalendarDate',
'CalendarDateRange',
'Callable',
'ClassSelector',
'Color',
'Composite',
'DEBUG',
'DataFrame',
'Date',
'DateRange',
'Dict',
'Dynamic',
'ERROR',
'Event',
'FileSelector',
'Filename',
'Foldername',
'HookList',
'INFO',
'Infinity',
'Integer',
'List',
'ListProxy',
'ListSelector',
'Magnitude',
'MultiFileSelector',
'Number',
'NumericTuple',
'ObjectSelector',
'ParamOverrides',
'Parameter',
'Parameterized',
'ParameterizedFunction',
'Path',
'Range',
'Selector',
'SelectorBase',
'Series',
'Skip',
'String',
'Time',
'Tuple',
'Undefined',
'VERBOSE',
'WARNING',
'XYCoordinates',
'__version__',
'_is_number',
'abbreviate_paths',
'as_unicode',
'batch_watch',
'bind',
'concrete_descendents',
'depends',
'descendents',
'discard_events',
'edit_constant',
'exceptions_summarized',
'get_logger',
'get_soft_bounds',
'guess_bounds',
'guess_param_types',
'hashable',
'is_ordered_dict',
'logging_level',
'main',
'named_objs',
'normalize_path',
'output',
'param_union',
'parameterized_class',
'produce_value',
'random_seed',
'resolve_path',
'rx',
'script_repr',
'serializer',
'shared_parameters',
'version',
)
param-2.1.1/param/_utils.py 0000664 0000000 0000000 00000044152 14636363363 0015607 0 ustar 00root root 0000000 0000000 import asyncio
import collections
import contextvars
import datetime as dt
import inspect
import functools
import numbers
import os
import re
import sys
import traceback
import warnings
from collections import defaultdict, OrderedDict
from contextlib import contextmanager
from numbers import Real
from textwrap import dedent
from threading import get_ident
from collections import abc
DEFAULT_SIGNATURE = inspect.Signature([
inspect.Parameter('self', inspect.Parameter.POSITIONAL_OR_KEYWORD),
inspect.Parameter('params', inspect.Parameter.VAR_KEYWORD),
])
MUTABLE_TYPES = (abc.MutableSequence, abc.MutableSet, abc.MutableMapping)
class ParamWarning(Warning):
"""Base Param Warning"""
class ParamPendingDeprecationWarning(ParamWarning, PendingDeprecationWarning):
"""Param PendingDeprecationWarning
This warning type is useful when the warning is not meant to be displayed
to REPL/notebooks users, as DeprecationWarning are displayed when triggered
by code in __main__ (__name__ == '__main__' in a REPL).
"""
class ParamDeprecationWarning(ParamWarning, DeprecationWarning):
"""Param DeprecationWarning
Ignored by default except when triggered by code in __main__
"""
class ParamFutureWarning(ParamWarning, FutureWarning):
"""Param FutureWarning
Always displayed.
"""
class Skip(Exception):
"""
Exception that allows skipping an update when resolving a reference.
"""
def _deprecated(extra_msg="", warning_cat=ParamDeprecationWarning):
def decorator(func):
"""Internal decorator used to mark functions/methods as deprecated."""
@functools.wraps(func)
def inner(*args, **kwargs):
msg = f"{func.__name__!r} has been deprecated and will be removed in a future version."
if extra_msg:
em = dedent(extra_msg)
em = em.strip().replace('\n', ' ')
msg = msg + ' ' + em
warnings.warn(msg, category=warning_cat, stacklevel=2)
return func(*args, **kwargs)
return inner
return decorator
def _deprecate_positional_args(func):
"""Internal decorator for methods that issues warnings for positional arguments
Using the keyword-only argument syntax in pep 3102, arguments after the
``*`` will issue a warning when passed as a positional argument.
Adapted from scikit-learn
"""
signature = inspect.signature(func)
pos_or_kw_args = []
kwonly_args = []
for name, param in signature.parameters.items():
if param.kind in (inspect.Parameter.POSITIONAL_OR_KEYWORD, inspect.Parameter.POSITIONAL_ONLY):
pos_or_kw_args.append(name)
elif param.kind == inspect.Parameter.KEYWORD_ONLY:
kwonly_args.append(name)
@functools.wraps(func)
def inner(*args, **kwargs):
name = func.__qualname__.split('.')[0]
n_extra_args = len(args) - len(pos_or_kw_args)
if n_extra_args > 0:
extra_args = ", ".join(kwonly_args[:n_extra_args])
warnings.warn(
f"Passing '{extra_args}' as positional argument(s) to 'param.{name}' "
"has been deprecated since Param 2.0.0 and will raise an error in a future version, "
"please pass them as keyword arguments.",
ParamDeprecationWarning,
stacklevel=2,
)
zip_args = zip(kwonly_args[:n_extra_args], args[-n_extra_args:])
kwargs.update({name: arg for name, arg in zip_args})
return func(*args[:-n_extra_args], **kwargs)
return func(*args, **kwargs)
return inner
# Copy of Python 3.2 reprlib's recursive_repr but allowing extra arguments
def _recursive_repr(fillvalue='...'):
'Decorator to make a repr function return fillvalue for a recursive call'
def decorating_function(user_function):
repr_running = set()
def wrapper(self, *args, **kwargs):
key = id(self), get_ident()
if key in repr_running:
return fillvalue
repr_running.add(key)
try:
result = user_function(self, *args, **kwargs)
finally:
repr_running.discard(key)
return result
return wrapper
return decorating_function
def _is_auto_name(class_name, instance_name):
return re.match('^'+class_name+'[0-9]{5}$', instance_name)
def _find_pname(pclass):
"""
Go up the stack and attempt to find a Parameter declaration of the form
`pname = param.Parameter(` or `pname = pm.Parameter(`.
"""
stack = traceback.extract_stack()
for frame in stack:
match = re.match(r"^(\S+)\s*=\s*(param|pm)\." + pclass + r"\(", frame.line)
if match:
return match.group(1)
def _validate_error_prefix(parameter, attribute=None):
"""
Generate an error prefix suitable for Parameters when they raise a validation
error.
- unbound and name can't be found: "Number parameter"
- unbound and name can be found: "Number parameter 'x'"
- bound parameter: "Number parameter 'P.x'"
"""
from param.parameterized import ParameterizedMetaclass
pclass = type(parameter).__name__
if parameter.owner is not None:
if type(parameter.owner) is ParameterizedMetaclass:
powner = parameter.owner.__name__
else:
powner = type(parameter.owner).__name__
else:
powner = None
pname = parameter.name
out = []
if attribute:
out.append(f'Attribute {attribute!r} of')
out.append(f'{pclass} parameter')
if pname:
if powner:
desc = f'{powner}.{pname}'
else:
desc = pname
out.append(f'{desc!r}')
else:
try:
pname = _find_pname(pclass)
if pname:
out.append(f'{pname!r}')
except Exception:
pass
return ' '.join(out)
def _is_mutable_container(value):
"""True for mutable containers, which typically need special handling when being copied"""
return issubclass(type(value), MUTABLE_TYPES)
def _dict_update(dictionary, **kwargs):
"""
Small utility to update a copy of a dict with the provided keyword args.
"""
d = dictionary.copy()
d.update(kwargs)
return d
def full_groupby(l, key=lambda x: x):
"""
Groupby implementation which does not require a prior sort
"""
d = defaultdict(list)
for item in l:
d[key(item)].append(item)
return d.items()
def iscoroutinefunction(function):
"""
Whether the function is an asynchronous generator or a coroutine.
"""
# Partial unwrapping not required starting from Python 3.11.0
# See https://github.com/holoviz/param/pull/894#issuecomment-1867084447
while isinstance(function, functools.partial):
function = function.func
return (
inspect.isasyncgenfunction(function) or
inspect.iscoroutinefunction(function)
)
async def _to_thread(func, /, *args, **kwargs):
"""
Polyfill for asyncio.to_thread in Python < 3.9
"""
loop = asyncio.get_running_loop()
ctx = contextvars.copy_context()
func_call = functools.partial(ctx.run, func, *args, **kwargs)
return await loop.run_in_executor(None, func_call)
async def _to_async_gen(sync_gen):
done = object()
def safe_next():
# Converts StopIteration to a sentinel value to avoid:
# TypeError: StopIteration interacts badly with generators and cannot be raised into a Future
try:
return next(sync_gen)
except StopIteration:
return done
while True:
if sys.version_info >= (3, 9):
value = await asyncio.to_thread(safe_next)
else:
value = await _to_thread(safe_next)
if value is done:
break
yield value
def flatten(line):
"""
Flatten an arbitrarily nested sequence.
Inspired by: pd.core.common.flatten
Parameters
----------
line : sequence
The sequence to flatten
Notes
-----
This only flattens list, tuple, and dict sequences.
Returns
-------
flattened : generator
"""
for element in line:
if any(isinstance(element, tp) for tp in (list, tuple, dict)):
yield from flatten(element)
else:
yield element
def accept_arguments(f):
"""
Decorator for decorators that accept arguments
"""
@functools.wraps(f)
def _f(*args, **kwargs):
return lambda actual_f: f(actual_f, *args, **kwargs)
return _f
def _produce_value(value_obj):
"""
A helper function that produces an actual parameter from a stored
object: if the object is callable, call it, otherwise return the
object.
"""
if callable(value_obj):
return value_obj()
else:
return value_obj
# PARAM3_DEPRECATION
@_deprecated()
def produce_value(value_obj):
"""
A helper function that produces an actual parameter from a stored
object: if the object is callable, call it, otherwise return the
object.
.. deprecated:: 2.0.0
"""
return _produce_value(value_obj)
# PARAM3_DEPRECATION
@_deprecated()
def as_unicode(obj):
"""
Safely casts any object to unicode including regular string
(i.e. bytes) types in python 2.
.. deprecated:: 2.0.0
"""
return str(obj)
# PARAM3_DEPRECATION
@_deprecated()
def is_ordered_dict(d):
"""
Predicate checking for ordered dictionaries. OrderedDict is always
ordered, and vanilla Python dictionaries are ordered for Python 3.6+
.. deprecated:: 2.0.0
"""
py3_ordered_dicts = (sys.version_info.major == 3) and (sys.version_info.minor >= 6)
vanilla_odicts = (sys.version_info.major > 3) or py3_ordered_dicts
return isinstance(d, (OrderedDict)) or (vanilla_odicts and isinstance(d, dict))
def _hashable(x):
"""
Return a hashable version of the given object x, with lists and
dictionaries converted to tuples. Allows mutable objects to be
used as a lookup key in cases where the object has not actually
been mutated. Lookup will fail (appropriately) in cases where some
part of the object has changed. Does not (currently) recursively
replace mutable subobjects.
"""
if isinstance(x, collections.abc.MutableSequence):
return tuple(x)
elif isinstance(x, collections.abc.MutableMapping):
return tuple([(k,v) for k,v in x.items()])
else:
return x
# PARAM3_DEPRECATION
@_deprecated()
def hashable(x):
"""
Return a hashable version of the given object x, with lists and
dictionaries converted to tuples. Allows mutable objects to be
used as a lookup key in cases where the object has not actually
been mutated. Lookup will fail (appropriately) in cases where some
part of the object has changed. Does not (currently) recursively
replace mutable subobjects.
.. deprecated:: 2.0.0
"""
return _hashable(x)
def _named_objs(objlist, namesdict=None):
"""
Given a list of objects, returns a dictionary mapping from
string name for the object to the object itself. Accepts
an optional name,obj dictionary, which will override any other
name if that item is present in the dictionary.
"""
objs = OrderedDict()
objtoname = {}
unhashables = []
if namesdict is not None:
for k, v in namesdict.items():
try:
objtoname[_hashable(v)] = k
except TypeError:
unhashables.append((k, v))
for obj in objlist:
if objtoname and _hashable(obj) in objtoname:
k = objtoname[_hashable(obj)]
elif any(obj is v for (_, v) in unhashables):
k = [k for (k, v) in unhashables if v is obj][0]
elif hasattr(obj, "name"):
k = obj.name
elif hasattr(obj, '__name__'):
k = obj.__name__
else:
k = str(obj)
objs[k] = obj
return objs
# PARAM3_DEPRECATION
@_deprecated()
def named_objs(objlist, namesdict=None):
"""
Given a list of objects, returns a dictionary mapping from
string name for the object to the object itself. Accepts
an optional name,obj dictionary, which will override any other
name if that item is present in the dictionary.
.. deprecated:: 2.0.0
"""
return _named_objs(objlist, namesdict=namesdict)
def _get_min_max_value(min, max, value=None, step=None):
"""Return min, max, value given input values with possible None."""
# Either min and max need to be given, or value needs to be given
if value is None:
if min is None or max is None:
raise ValueError(
f'unable to infer range, value from: ({min}, {max}, {value})'
)
diff = max - min
value = min + (diff / 2)
# Ensure that value has the same type as diff
if not isinstance(value, type(diff)):
value = min + (diff // 2)
else: # value is not None
if not isinstance(value, Real):
raise TypeError('expected a real number, got: %r' % value)
# Infer min/max from value
if value == 0:
# This gives (0, 1) of the correct type
vrange = (value, value + 1)
elif value > 0:
vrange = (-value, 3*value)
else:
vrange = (3*value, -value)
if min is None:
min = vrange[0]
if max is None:
max = vrange[1]
if step is not None:
# ensure value is on a step
tick = int((value - min) / step)
value = min + tick * step
if not min <= value <= max:
raise ValueError(f'value must be between min and max (min={min}, value={value}, max={max})')
return min, max, value
def _deserialize_from_path(ext_to_routine, path, type_name):
"""
Call deserialization routine with path according to extension.
ext_to_routine should be a dictionary mapping each supported
file extension to a corresponding loading function.
"""
if not os.path.isfile(path):
raise FileNotFoundError(
"Could not parse file '{}' as {}: does not exist or is not a file"
"".format(path, type_name))
root, ext = os.path.splitext(path)
if ext in {'.gz', '.bz2', '.xz', '.zip'}:
# A compressed type. We'll assume the routines can handle such extensions
# transparently (if not, we'll fail later)
ext = os.path.splitext(root)[1]
# FIXME(sdrobert): try...except block below with "raise from" might be a good idea
# once py2.7 support is removed. Provides error + fact that failure occurred in
# deserialization
if ext in ext_to_routine:
return ext_to_routine[ext](path)
raise ValueError(
"Could not parse file '{}' as {}: no deserialization method for files with "
"'{}' extension. Supported extensions: {}"
"".format(path, type_name, ext, ', '.join(sorted(ext_to_routine))))
def _is_number(obj):
if isinstance(obj, numbers.Number): return True
# The extra check is for classes that behave like numbers, such as those
# found in numpy, gmpy, etc.
elif (hasattr(obj, '__int__') and hasattr(obj, '__add__')): return True
# This is for older versions of gmpy
elif hasattr(obj, 'qdiv'): return True
else: return False
def _is_abstract(class_):
try:
return class_.abstract
except AttributeError:
return False
def descendents(class_):
"""
Return a list of the class hierarchy below (and including) the given class.
The list is ordered from least- to most-specific. Can be useful for
printing the contents of an entire class hierarchy.
"""
assert isinstance(class_,type)
q = [class_]
out = []
while len(q):
x = q.pop(0)
out.insert(0,x)
for b in x.__subclasses__():
if b not in q and b not in out:
q.append(b)
return out[::-1]
# Could be a method of ClassSelector.
def concrete_descendents(parentclass):
"""
Return a dictionary containing all subclasses of the specified
parentclass, including the parentclass. Only classes that are
defined in scripts that have been run or modules that have been
imported are included, so the caller will usually first do ``from
package import *``.
Only non-abstract classes will be included.
"""
return {c.__name__:c for c in descendents(parentclass)
if not _is_abstract(c)}
def _abbreviate_paths(pathspec,named_paths):
"""
Given a dict of (pathname,path) pairs, removes any prefix shared by all pathnames.
Helps keep menu items short yet unambiguous.
"""
from os.path import commonprefix, dirname, sep
prefix = commonprefix([dirname(name)+sep for name in named_paths.keys()]+[pathspec])
return OrderedDict([(name[len(prefix):],path) for name,path in named_paths.items()])
# PARAM3_DEPRECATION
@_deprecated()
def abbreviate_paths(pathspec,named_paths):
"""
Given a dict of (pathname,path) pairs, removes any prefix shared by all pathnames.
Helps keep menu items short yet unambiguous.
.. deprecated:: 2.0.0
"""
return _abbreviate_paths(pathspec, named_paths)
def _to_datetime(x):
"""
Internal function that will convert date objs to datetime objs, used
for comparing date and datetime objects without error.
"""
if isinstance(x, dt.date) and not isinstance(x, dt.datetime):
return dt.datetime(*x.timetuple()[:6])
return x
@contextmanager
def exceptions_summarized():
"""Useful utility for writing docs that need to show expected errors.
Shows exception only, concisely, without a traceback.
"""
try:
yield
except Exception:
import sys
etype, value, tb = sys.exc_info()
print(f"{etype.__name__}: {value}", file=sys.stderr)
def _in_ipython():
try:
get_ipython()
return True
except NameError:
return False
_running_tasks = set()
def async_executor(func):
try:
event_loop = asyncio.get_running_loop()
except RuntimeError:
event_loop = asyncio.new_event_loop()
if event_loop.is_running():
task = asyncio.ensure_future(func())
_running_tasks.add(task)
task.add_done_callback(_running_tasks.discard)
else:
event_loop.run_until_complete(func())
param-2.1.1/param/depends.py 0000664 0000000 0000000 00000012151 14636363363 0015724 0 ustar 00root root 0000000 0000000 import inspect
from collections import defaultdict
from functools import wraps
from .parameterized import (
Parameter, Parameterized, ParameterizedMetaclass, transform_reference,
)
from ._utils import accept_arguments, iscoroutinefunction
@accept_arguments
def depends(func, *dependencies, watch=False, on_init=False, **kw):
"""Annotates a function or Parameterized method to express its dependencies.
The specified dependencies can be either be Parameter instances or if a
method is supplied they can be defined as strings referring to Parameters
of the class, or Parameters of subobjects (Parameterized objects that are
values of this object's parameters). Dependencies can either be on
Parameter values, or on other metadata about the Parameter.
Parameters
----------
watch : bool, optional
Whether to invoke the function/method when the dependency is updated,
by default False
on_init : bool, optional
Whether to invoke the function/method when the instance is created,
by default False
"""
dependencies, kw = (
tuple(transform_reference(arg) for arg in dependencies),
{key: transform_reference(arg) for key, arg in kw.items()}
)
if inspect.isgeneratorfunction(func):
@wraps(func)
def _depends(*args, **kw):
for val in func(*args, **kw):
yield val
elif inspect.isasyncgenfunction(func):
@wraps(func)
async def _depends(*args, **kw):
async for val in func(*args, **kw):
yield val
elif iscoroutinefunction(func):
@wraps(func)
async def _depends(*args, **kw):
return await func(*args, **kw)
else:
@wraps(func)
def _depends(*args, **kw):
return func(*args, **kw)
deps = list(dependencies)+list(kw.values())
string_specs = False
for dep in deps:
if isinstance(dep, str):
string_specs = True
elif hasattr(dep, '_dinfo'):
pass
elif not isinstance(dep, Parameter):
raise ValueError('The depends decorator only accepts string '
'types referencing a parameter or parameter '
'instances, found %s type instead.' %
type(dep).__name__)
elif not (isinstance(dep.owner, Parameterized) or
(isinstance(dep.owner, ParameterizedMetaclass))):
owner = 'None' if dep.owner is None else '%s class' % type(dep.owner).__name__
raise ValueError('Parameters supplied to the depends decorator, '
'must be bound to a Parameterized class or '
'instance, not %s.' % owner)
if (any(isinstance(dep, Parameter) for dep in deps) and
any(isinstance(dep, str) for dep in deps)):
raise ValueError('Dependencies must either be defined as strings '
'referencing parameters on the class defining '
'the decorated method or as parameter instances. '
'Mixing of string specs and parameter instances '
'is not supported.')
elif string_specs and kw:
raise AssertionError('Supplying keywords to the decorated method '
'or function is not supported when referencing '
'parameters by name.')
if not string_specs and watch: # string_specs case handled elsewhere (later), in Parameterized.__init__
if inspect.isgeneratorfunction(func):
def cb(*events):
args = (getattr(dep.owner, dep.name) for dep in dependencies)
dep_kwargs = {n: getattr(dep.owner, dep.name) for n, dep in kw.items()}
for val in func(*args, **dep_kwargs):
yield val
elif inspect.isasyncgenfunction(func):
async def cb(*events):
args = (getattr(dep.owner, dep.name) for dep in dependencies)
dep_kwargs = {n: getattr(dep.owner, dep.name) for n, dep in kw.items()}
async for val in func(*args, **dep_kwargs):
yield val
elif iscoroutinefunction(func):
async def cb(*events):
args = (getattr(dep.owner, dep.name) for dep in dependencies)
dep_kwargs = {n: getattr(dep.owner, dep.name) for n, dep in kw.items()}
await func(*args, **dep_kwargs)
else:
def cb(*events):
args = (getattr(dep.owner, dep.name) for dep in dependencies)
dep_kwargs = {n: getattr(dep.owner, dep.name) for n, dep in kw.items()}
return func(*args, **dep_kwargs)
grouped = defaultdict(list)
for dep in deps:
grouped[id(dep.owner)].append(dep)
for group in grouped.values():
group[0].owner.param.watch(cb, [dep.name for dep in group])
_dinfo = getattr(func, '_dinfo', {})
_dinfo.update({'dependencies': dependencies,
'kw': kw, 'watch': watch, 'on_init': on_init})
_depends._dinfo = _dinfo
return _depends
param-2.1.1/param/display.py 0000664 0000000 0000000 00000001466 14636363363 0015756 0 ustar 00root root 0000000 0000000 import weakref
_display_accessors = {}
_reactive_display_objs = weakref.WeakSet()
def register_display_accessor(name, accessor, force=False):
if name in _display_accessors and not force:
if _display_accessors[name].__module__ != accessor.__module__:
raise KeyError(
f'Display accessor {name!r} already registered. Override it '
'by setting force=True or unregister the existing accessor first.'
)
_display_accessors[name] = accessor
for fn in _reactive_display_objs:
setattr(fn, name, accessor(fn))
def unregister_display_accessor(name):
if name not in _display_accessors:
raise KeyError('No such display accessor: {name!r}')
del _display_accessors[name]
for fn in _reactive_display_objs:
delattr(fn, name)
param-2.1.1/param/ipython.py 0000664 0000000 0000000 00000035262 14636363363 0016004 0 ustar 00root root 0000000 0000000 """
Optional IPython extension for working with Parameters.
This extension offers extended but completely optional functionality
for IPython users. From within IPython, it may be loaded using:
%load_ext param.ipython
This will register the %params line magic to allow easy inspection of
all the parameters defined on a parameterized class or object:
%params
All parameters of the class or object will be listed in the IPython
pager together with all their corresponding attributes and
docstrings. Note that the class or object to be inspected must already
exist in the active namespace.
"""
import re
import itertools
import textwrap
import uuid
import param
from param.display import register_display_accessor
from param._utils import async_executor
# Whether to generate warnings when misformatted docstrings are found
WARN_MISFORMATTED_DOCSTRINGS = False
# ANSI color codes for the IPython pager
red = '\x1b[1;31m%s\x1b[0m'
blue = '\x1b[1;34m%s\x1b[0m'
green = '\x1b[1;32m%s\x1b[0m'
cyan = '\x1b[1;36m%s\x1b[0m'
class ParamPager:
"""
Callable class that displays information about the supplied
Parameterized object or class in the IPython pager.
"""
def __init__(self, metaclass=False):
"""
If metaclass is set to True, the checks for Parameterized
classes objects are disabled. This option is for use in
ParameterizedMetaclass for automatic docstring generation.
"""
# Order of the information to be listed in the table (left to right)
self.order = ['name', 'changed', 'value', 'type', 'bounds', 'mode']
self.metaclass = metaclass
def get_param_info(self, obj, include_super=True):
"""
Get the parameter dictionary, the list of modifed parameters
and the dictionary of parameter values. If include_super is
True, parameters are also collected from the super classes.
"""
params = dict(obj.param.objects('existing'))
if isinstance(obj,type):
changed = []
val_dict = {k:p.default for (k,p) in params.items()}
self_class = obj
else:
changed = list(obj.param.values(onlychanged=True).keys())
val_dict = obj.param.values()
self_class = obj.__class__
if not include_super:
params = {k:v for (k,v) in params.items()
if k in self_class.__dict__}
params.pop('name') # Already displayed in the title.
return (params, val_dict, changed)
def param_docstrings(self, info, max_col_len=100, only_changed=False):
"""
Build a string to that presents all of the parameter
docstrings in a clean format (alternating red and blue for
readability).
"""
(params, val_dict, changed) = info
contents = []
displayed_params = []
for name in self.sort_by_precedence(params):
if only_changed and not (name in changed):
continue
displayed_params.append((name, params[name]))
right_shift = max(len(name) for name, _ in displayed_params)+2
for i, (name, p) in enumerate(displayed_params):
heading = "%s: " % name
unindented = textwrap.dedent("< No docstring available >" if p.doc is None else p.doc)
if (WARN_MISFORMATTED_DOCSTRINGS
and not unindented.startswith("\n") and len(unindented.splitlines()) > 1):
param.main.warning("Multi-line docstring for %r is incorrectly formatted "
" (should start with newline)", name)
# Strip any starting newlines
while unindented.startswith("\n"):
unindented = unindented[1:]
lines = unindented.splitlines()
if len(lines) > 1:
tail = [f"{' ' * right_shift}{line}" for line in lines[1:]]
all_lines = [ heading.ljust(right_shift) + lines[0]] + tail
elif len(lines) == 1:
all_lines = [ heading.ljust(right_shift) + lines[0]]
else:
all_lines = []
if i % 2: # Alternate red and blue for docstrings
contents.extend([red %el for el in all_lines])
else:
contents.extend([blue %el for el in all_lines])
return "\n".join(contents)
def sort_by_precedence(self, parameters):
"""
Sort the provided dictionary of parameters by their precedence value,
preserving the original ordering for parameters with the
same precedence.
"""
params = [(p, pobj) for p, pobj in parameters.items()]
key_fn = lambda x: x[1].precedence if x[1].precedence is not None else 1e-8
sorted_params = sorted(params, key=key_fn)
groups = itertools.groupby(sorted_params, key=key_fn)
ordered_groups = [list(grp) for (_, grp) in groups]
ordered_params = [el[0] for group in ordered_groups for el in group
if (el[0] != 'name' or el[0] in parameters)]
return ordered_params
def _build_table(self, info, order, max_col_len=40, only_changed=False):
"""
Collect the information about parameters needed to build a
properly formatted table and then tabulate it.
"""
info_list, bounds_dict = [], {}
(params, val_dict, changed) = info
col_widths = {k:0 for k in order}
ordering = self.sort_by_precedence(params)
for name in ordering:
p = params[name]
if only_changed and not (name in changed):
continue
constant = 'C' if p.constant else 'V'
readonly = 'RO' if p.readonly else 'RW'
allow_None = ' AN' if hasattr(p, 'allow_None') and p.allow_None else ''
mode = f'{constant} {readonly}{allow_None}'
value = repr(val_dict[name])
if len(value) > (max_col_len - 3):
value = value[:max_col_len-3] + '...'
p_dict = {'name': name, 'type': p.__class__.__name__,
'mode': mode, 'value': value}
if hasattr(p, 'bounds'):
lbound, ubound = (None,None) if p.bounds is None else p.bounds
mark_lbound, mark_ubound = False, False
# Use soft_bounds when bounds not defined.
if hasattr(p, 'get_soft_bounds'):
soft_lbound, soft_ubound = p.get_soft_bounds()
if lbound is None and soft_lbound is not None:
lbound = soft_lbound
mark_lbound = True
if ubound is None and soft_ubound is not None:
ubound = soft_ubound
mark_ubound = True
if (lbound, ubound) != (None,None):
bounds_dict[name] = (mark_lbound, mark_ubound)
p_dict['bounds'] = f'({lbound}, {ubound})'
for col in p_dict:
max_width = max([col_widths[col], len(p_dict[col])])
col_widths[col] = max_width
info_list.append((name, p_dict))
return self._tabulate(info_list, col_widths, changed, order, bounds_dict)
def _tabulate(self, info_list, col_widths, changed, order, bounds_dict):
"""
Returns the supplied information as a table suitable for
printing or paging.
info_list: List of the parameters name, type and mode.
col_widths: Dictionary of column widths in characters
changed: List of parameters modified from their defaults.
order: The order of the table columns
bound_dict: Dictionary of appropriately formatted bounds
"""
contents, tail = [], []
column_set = {k for _, row in info_list for k in row}
columns = [col for col in order if col in column_set]
title_row = []
# Generate the column headings
for i, col in enumerate(columns):
width = col_widths[col]+2
col = col.capitalize()
formatted = col.ljust(width) if i == 0 else col.center(width)
title_row.append(formatted)
contents.append(blue % ''.join(title_row)+"\n")
# Format the table rows
for row, info in info_list:
row_list = []
for i,col in enumerate(columns):
width = col_widths[col]+2
val = info[col] if (col in info) else ''
formatted = val.ljust(width) if i==0 else val.center(width)
if col == 'bounds' and bounds_dict.get(row,False):
(mark_lbound, mark_ubound) = bounds_dict[row]
lval, uval = formatted.rsplit(',')
lspace, lstr = lval.rsplit('(')
ustr, uspace = uval.rsplit(')')
lbound = lspace + '('+(cyan % lstr) if mark_lbound else lval
ubound = (cyan % ustr)+')'+uspace if mark_ubound else uval
formatted = f"{lbound},{ubound}"
row_list.append(formatted)
row_text = ''.join(row_list)
if row in changed:
row_text = red % row_text
contents.append(row_text)
return '\n'.join(contents+tail)
def __call__(self, param_obj):
"""
Given a Parameterized object or class, display information
about the parameters in the IPython pager.
"""
title = None
if not self.metaclass:
parameterized_object = isinstance(param_obj, param.Parameterized)
parameterized_class = (isinstance(param_obj,type)
and issubclass(param_obj,param.Parameterized))
if not (parameterized_object or parameterized_class):
print("Object is not a Parameterized class or object.")
return
if parameterized_object:
# Only show the name if not autogenerated
class_name = param_obj.__class__.__name__
default_name = re.match('^'+class_name+'[0-9]+$', param_obj.name)
obj_name = '' if default_name else (' %r' % param_obj.name)
title = f'Parameters of {class_name!r} instance{obj_name}'
if title is None:
title = 'Parameters of %r' % param_obj.name
heading_line = '=' * len(title)
heading_text = f"{title}\n{heading_line}\n"
param_info = self.get_param_info(param_obj, include_super=True)
if not param_info[0]:
top_heading = green % heading_text
return f"{top_heading}\nObject has no parameters."
table = self._build_table(param_info, self.order, max_col_len=40,
only_changed=False)
docstrings = self.param_docstrings(param_info, max_col_len=100, only_changed=False)
dflt_msg = "Parameters changed from their default values are marked in red."
top_heading = (green % heading_text)
top_heading += "\n%s" % (red % dflt_msg)
top_heading += "\n%s" % (cyan % "Soft bound values are marked in cyan.")
top_heading += '\nC/V= Constant/Variable, RO/RW = ReadOnly/ReadWrite, AN=Allow None'
heading_text = 'Parameter docstrings:'
heading_string = f"{heading_text}\n{'=' * len(heading_text)}"
docstring_heading = (green % heading_string)
return f"{top_heading}\n\n{table}\n\n{docstring_heading}\n\n{docstrings}"
message = """Welcome to the param IPython extension! (https://param.holoviz.org/)"""
message += '\nAvailable magics: %params'
_loaded = False
def load_ipython_extension(ip, verbose=True):
from IPython.core.magic import Magics, magics_class, line_magic
from IPython.core import page
@magics_class
class ParamMagics(Magics):
"""
Implements the %params line magic used to inspect the parameters
of a parameterized class or object.
"""
def __init__(self, *args, **kwargs):
super().__init__(*args, **kwargs)
self.param_pager = ParamPager()
@line_magic
def params(self, parameter_s='', namespaces=None):
"""
The %params line magic accepts a single argument which is a
handle on the parameterized object to be inspected. If the
object can be found in the active namespace, information about
the object's parameters is displayed in the IPython pager.
Usage: %params
"""
if parameter_s=='':
print("Please specify an object to inspect.")
return
# Beware! Uses IPython internals that may change in future...
obj = self.shell._object_find(parameter_s)
if obj.found is False:
print("Object %r not found in the namespace." % parameter_s)
return
page.page(self.param_pager(obj.obj))
if verbose: print(message)
global _loaded
if not _loaded:
_loaded = True
ip.register_magics(ParamMagics)
class IPythonDisplay:
"""
Reactive display handler that updates the output.
"""
enabled = True
def __init__(self, reactive):
self._reactive = reactive
def __call__(self):
from param.depends import depends
from param.parameterized import Undefined, resolve_ref
from param.reactive import rx
handle = None
if isinstance(self._reactive, rx):
cb = self._reactive._callback
@depends(*self._reactive._params, watch=True)
def update_handle(*args, **kwargs):
if handle is not None:
handle.update(cb())
else:
cb = self._reactive
@depends(*resolve_ref(cb), watch=True)
def update_handle(*args, **kwargs):
if handle is not None:
handle.update(cb())
try:
obj = cb()
if obj is Undefined:
obj = None
handle = display(obj, display_id=uuid.uuid4().hex) # noqa
except TypeError:
raise NotImplementedError
def ipython_async_executor(func):
event_loop = None
try:
ip = get_ipython() # noqa
if ip.kernel:
# We are in Jupyter and can piggyback the tornado IOLoop
from tornado.ioloop import IOLoop
ioloop = IOLoop.current()
event_loop = ioloop.asyncio_loop # type: ignore
if event_loop.is_running():
ioloop.add_callback(func)
else:
event_loop.run_until_complete(func())
return
except (NameError, AttributeError):
pass
async_executor(func)
register_display_accessor('_ipython_display_', IPythonDisplay)
param-2.1.1/param/parameterized.py 0000664 0000000 0000000 00000536031 14636363363 0017146 0 ustar 00root root 0000000 0000000 """
Generic support for objects with full-featured Parameters and
messaging.
This file comes from the Param library (https://github.com/holoviz/param)
but can be taken out of the param module and used on its own if desired,
either alone (providing basic Parameter support) or with param's
__init__.py (providing specialized Parameter types).
"""
import asyncio
import copy
import datetime as dt
import html
import inspect
import logging
import numbers
import operator
import random
import re
import types
import typing
import warnings
# Allow this file to be used standalone if desired, albeit without JSON serialization
try:
from . import serializer
except ImportError:
serializer = None
from collections import defaultdict, namedtuple, OrderedDict
from functools import partial, wraps, reduce
from html import escape
from itertools import chain
from operator import itemgetter, attrgetter
from types import FunctionType, MethodType
from contextlib import contextmanager
from logging import DEBUG, INFO, WARNING, ERROR, CRITICAL
from ._utils import (
DEFAULT_SIGNATURE,
ParamDeprecationWarning as _ParamDeprecationWarning,
ParamFutureWarning as _ParamFutureWarning,
Skip,
_deprecated,
_deprecate_positional_args,
_dict_update,
_in_ipython,
_is_auto_name,
_is_mutable_container,
_recursive_repr,
_to_async_gen,
_validate_error_prefix,
accept_arguments,
iscoroutinefunction,
descendents,
)
# Ideally setting param_pager would be in __init__.py but param_pager is
# needed on import to create the Parameterized class, so it'd need to precede
# importing parameterized.py in __init__.py which would be a little weird.
if _in_ipython():
# In case the optional ipython module is unavailable
try:
from .ipython import ParamPager, ipython_async_executor as async_executor
param_pager = ParamPager(metaclass=True) # Generates param description
except ImportError:
from ._utils import async_executor
else:
from ._utils import async_executor
param_pager = None
from inspect import getfullargspec
dt_types = (dt.datetime, dt.date)
_int_types = (int,)
try:
import numpy as np
dt_types = dt_types + (np.datetime64,)
_int_types = _int_types + (np.integer,)
except:
pass
VERBOSE = INFO - 1
logging.addLevelName(VERBOSE, "VERBOSE")
# Get the appropriate logging.Logger instance. If `logger` is None, a
# logger named `"param"` will be instantiated. If `name` is set, a descendant
# logger with the name ``"param."`` is returned (or
# ``logger.name + "."``)
logger = None
def get_logger(name=None):
if logger is None:
root_logger = logging.getLogger('param')
if not root_logger.handlers:
root_logger.setLevel(logging.INFO)
formatter = logging.Formatter(
fmt='%(levelname)s:%(name)s: %(message)s')
handler = logging.StreamHandler()
handler.setFormatter(formatter)
root_logger.addHandler(handler)
else:
root_logger = logger
if name is None:
return root_logger
else:
return logging.getLogger(root_logger.name + '.' + name)
# Indicates whether warnings should be raised as errors, stopping
# processing.
warnings_as_exceptions = False
docstring_signature = True # Add signature to class docstrings
docstring_describe_params = True # Add parameter description to class
# docstrings (requires ipython module)
object_count = 0
warning_count = 0
# Hook to apply to depends and bind arguments to turn them into valid parameters
_reference_transforms = []
def register_reference_transform(transform):
"""
Appends a transform to extract potential parameter dependencies
from an object.
Arguments
---------
transform: Callable[Any, Any]
"""
return _reference_transforms.append(transform)
def transform_reference(arg):
"""
Applies transforms to turn objects which should be treated like
a parameter reference into a valid reference that can be resolved
by Param. This is useful for adding handling for depending on objects
that are not simple Parameters or functions with dependency
definitions.
"""
for transform in _reference_transforms:
if isinstance(arg, Parameter) or hasattr(arg, '_dinfo'):
break
arg = transform(arg)
return arg
def eval_function_with_deps(function):
"""Evaluates a function after resolving its dependencies.
Calls and returns a function after resolving any dependencies
stored on the _dinfo attribute and passing the resolved values
as arguments.
"""
args, kwargs = (), {}
if hasattr(function, '_dinfo'):
arg_deps = function._dinfo['dependencies']
kw_deps = function._dinfo.get('kw', {})
if kw_deps or any(isinstance(d, Parameter) for d in arg_deps):
args = (getattr(dep.owner, dep.name) for dep in arg_deps)
kwargs = {n: getattr(dep.owner, dep.name) for n, dep in kw_deps.items()}
return function(*args, **kwargs)
def resolve_value(value, recursive=True):
"""
Resolves the current value of a dynamic reference.
"""
if not recursive:
pass
elif isinstance(value, (list, tuple)):
return type(value)(resolve_value(v) for v in value)
elif isinstance(value, dict):
return type(value)((resolve_value(k), resolve_value(v)) for k, v in value.items())
elif isinstance(value, slice):
return slice(
resolve_value(value.start),
resolve_value(value.stop),
resolve_value(value.step)
)
value = transform_reference(value)
is_gen = inspect.isgeneratorfunction(value)
if hasattr(value, '_dinfo') or iscoroutinefunction(value) or is_gen:
value = eval_function_with_deps(value)
if is_gen:
value = _to_async_gen(value)
elif isinstance(value, Parameter):
value = getattr(value.owner, value.name)
return value
def resolve_ref(reference, recursive=False):
"""
Resolves all parameters a dynamic reference depends on.
"""
if recursive:
if isinstance(reference, (list, tuple, set)):
return [r for v in reference for r in resolve_ref(v, recursive)]
elif isinstance(reference, dict):
return [r for kv in reference.items() for o in kv for r in resolve_ref(o, recursive)]
elif isinstance(reference, slice):
return [r for v in (reference.start, reference.stop, reference.step) for r in resolve_ref(v, recursive)]
reference = transform_reference(reference)
if hasattr(reference, '_dinfo'):
dinfo = getattr(reference, '_dinfo', {})
args = list(dinfo.get('dependencies', []))
kwargs = list(dinfo.get('kw', {}).values())
refs = []
for arg in (args + kwargs):
if isinstance(arg, str):
owner = get_method_owner(reference)
if arg in owner.param:
arg = owner.param[arg]
elif '.' in arg:
path = arg.split('.')
arg = owner
for attr in path[:-1]:
arg = getattr(arg, attr)
arg = arg.param[path[-1]]
else:
arg = getattr(owner, arg)
refs.extend(resolve_ref(arg))
return refs
elif isinstance(reference, Parameter):
return [reference]
return []
def _identity_hook(obj, val):
"""To be removed when set_hook is removed"""
return val
class _Undefined:
"""
Dummy value to signal completely undefined values rather than
simple None values.
"""
def __bool__(self):
# Haven't defined whether Undefined is falsy or truthy,
# so to avoid subtle bugs raise an error when it
# is used in a comparison without `is`.
raise RuntimeError('Use `is` to compare Undefined')
def __repr__(self):
return ''
Undefined = _Undefined()
@contextmanager
def logging_level(level):
"""
Temporarily modify param's logging level.
"""
level = level.upper()
levels = [DEBUG, INFO, WARNING, ERROR, CRITICAL, VERBOSE]
level_names = ['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL', 'VERBOSE']
if level not in level_names:
raise Exception(f"Level {level!r} not in {levels!r}")
param_logger = get_logger()
logging_level = param_logger.getEffectiveLevel()
param_logger.setLevel(levels[level_names.index(level)])
try:
yield None
finally:
param_logger.setLevel(logging_level)
@contextmanager
def _batch_call_watchers(parameterized, enable=True, run=True):
"""
Internal version of batch_call_watchers, adding control over queueing and running.
Only actually batches events if enable=True; otherwise a no-op. Only actually
calls the accumulated watchers on exit if run=True; otherwise they remain queued.
"""
BATCH_WATCH = parameterized.param._BATCH_WATCH
parameterized.param._BATCH_WATCH = enable or parameterized.param._BATCH_WATCH
try:
yield
finally:
parameterized.param._BATCH_WATCH = BATCH_WATCH
if run and not BATCH_WATCH:
parameterized.param._batch_call_watchers()
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `batch_call_watchers`.")
@contextmanager
def batch_watch(parameterized, enable=True, run=True):
with _batch_call_watchers(parameterized, enable, run):
yield
@contextmanager
def batch_call_watchers(parameterized):
"""
Context manager to batch events to provide to Watchers on a
parameterized object. This context manager queues any events
triggered by setting a parameter on the supplied parameterized
object, saving them up to dispatch them all at once when the
context manager exits.
"""
BATCH_WATCH = parameterized.param._BATCH_WATCH
parameterized.param._BATCH_WATCH = True
try:
yield
finally:
parameterized.param._BATCH_WATCH = BATCH_WATCH
if not BATCH_WATCH:
parameterized.param._batch_call_watchers()
@contextmanager
def _syncing(parameterized, parameters):
old = parameterized._param__private.syncing
parameterized._param__private.syncing = set(old) | set(parameters)
try:
yield
finally:
parameterized._param__private.syncing = old
@contextmanager
def edit_constant(parameterized):
"""
Temporarily set parameters on Parameterized object to constant=False
to allow editing them.
"""
params = parameterized.param.objects('existing').values()
constants = [p.constant for p in params]
for p in params:
p.constant = False
try:
yield
except:
raise
finally:
for (p, const) in zip(params, constants):
p.constant = const
@contextmanager
def discard_events(parameterized):
"""
Context manager that discards any events within its scope
triggered on the supplied parameterized object.
"""
batch_watch = parameterized.param._BATCH_WATCH
parameterized.param._BATCH_WATCH = True
watchers, events = (list(parameterized.param._state_watchers),
list(parameterized.param._events))
try:
yield
except:
raise
finally:
parameterized.param._BATCH_WATCH = batch_watch
parameterized.param._state_watchers = watchers
parameterized.param._events = events
def classlist(class_):
"""
Return a list of the class hierarchy above (and including) the given class.
Same as `inspect.getmro(class_)[::-1]`
"""
return inspect.getmro(class_)[::-1]
def get_all_slots(class_):
"""
Return a list of slot names for slots defined in `class_` and its
superclasses.
"""
# A subclass's __slots__ attribute does not contain slots defined
# in its superclass (the superclass' __slots__ end up as
# attributes of the subclass).
all_slots = []
parent_param_classes = [c for c in classlist(class_)[1::]]
for c in parent_param_classes:
if hasattr(c,'__slots__'):
all_slots+=c.__slots__
return all_slots
def get_occupied_slots(instance):
"""
Return a list of slots for which values have been set.
(While a slot might be defined, if a value for that slot hasn't
been set, then it's an AttributeError to request the slot's
value.)
"""
return [slot for slot in get_all_slots(type(instance))
if hasattr(instance,slot)]
# PARAM3_DEPRECATION
@_deprecated()
def all_equal(arg1,arg2):
"""
Return a single boolean for arg1==arg2, even for numpy arrays
using element-wise comparison.
Uses all(arg1==arg2) for sequences, and arg1==arg2 otherwise.
If both objects have an '_infinitely_iterable' attribute, they are
not be zipped together and are compared directly instead.
"""
if all(hasattr(el, '_infinitely_iterable') for el in [arg1,arg2]):
return arg1==arg2
try:
return all(a1 == a2 for a1, a2 in zip(arg1, arg2))
except TypeError:
return arg1==arg2
# PARAM3_DEPRECATION
# The syntax to use a metaclass changed incompatibly between 2 and
# 3. The add_metaclass() class decorator below creates a class using a
# specified metaclass in a way that works on both 2 and 3. For 3, can
# remove this decorator and specify metaclasses in a simpler way
# (https://docs.python.org/3/reference/datamodel.html#customizing-class-creation)
#
# Code from six (https://bitbucket.org/gutworth/six; version 1.4.1).
@_deprecated()
def add_metaclass(metaclass):
"""Class decorator for creating a class with a metaclass.
.. deprecated:: 2.0.0
"""
def wrapper(cls):
orig_vars = cls.__dict__.copy()
orig_vars.pop('__dict__', None)
orig_vars.pop('__weakref__', None)
for slots_var in orig_vars.get('__slots__', ()):
orig_vars.pop(slots_var)
return metaclass(cls.__name__, cls.__bases__, orig_vars)
return wrapper
class bothmethod:
"""
'optional @classmethod'
A decorator that allows a method to receive either the class
object (if called on the class) or the instance object
(if called on the instance) as its first argument.
"""
def __init__(self, method):
self.method = method
def __get__(self, instance, owner):
if instance is None:
# Class call
return self.method.__get__(owner)
else:
# Instance call
return self.method.__get__(instance, owner)
def _getattrr(obj, attr, *args):
def _getattr(obj, attr):
return getattr(obj, attr, *args)
return reduce(_getattr, [obj] + attr.split('.'))
def no_instance_params(cls):
"""
Disables instance parameters on the class
"""
cls._param__private.disable_instance_params = True
return cls
def _instantiate_param_obj(paramobj, owner=None):
"""Return a Parameter object suitable for instantiation given the class's Parameter object"""
# Shallow-copy Parameter object without the watchers
p = copy.copy(paramobj)
p.owner = owner
# Reset watchers since class parameter watcher should not execute
# on instance parameters
p.watchers = {}
# shallow-copy any mutable slot values other than the actual default
for s in p.__class__._all_slots_:
v = getattr(p, s)
if _is_mutable_container(v) and s != "default":
setattr(p, s, copy.copy(v))
return p
def _instantiated_parameter(parameterized, param):
"""
Given a Parameterized object and one of its class Parameter objects,
return the appropriate Parameter object for this instance, instantiating
it if need be.
"""
if (getattr(parameterized._param__private, 'initialized', False) and param.per_instance and
not getattr(type(parameterized)._param__private, 'disable_instance_params', False)):
key = param.name
if key not in parameterized._param__private.params:
parameterized._param__private.params[key] = _instantiate_param_obj(param, parameterized)
param = parameterized._param__private.params[key]
return param
def instance_descriptor(f):
# If parameter has an instance Parameter, delegate setting
def _f(self, obj, val):
# obj is None when the metaclass is setting
if obj is not None:
instance_param = obj._param__private.params.get(self.name)
if instance_param is None:
instance_param = _instantiated_parameter(obj, self)
if instance_param is not None and self is not instance_param:
instance_param.__set__(obj, val)
return
return f(self, obj, val)
return _f
def get_method_owner(method):
"""
Gets the instance that owns the supplied method
"""
if not inspect.ismethod(method):
return None
if isinstance(method, partial):
method = method.func
return method.__self__
# PARAM3_DEPRECATION
def recursive_repr(fillvalue='...'):
"""
Decorator to make a repr function return fillvalue for a recursive call
.. deprecated:: 1.12.0
"""
warnings.warn(
'recursive_repr has been deprecated and will be removed in a future version.',
category=_ParamDeprecationWarning,
stacklevel=2,
)
return _recursive_repr(fillvalue=fillvalue)
@accept_arguments
def output(func, *output, **kw):
"""
output allows annotating a method on a Parameterized class to
declare that it returns an output of a specific type. The outputs
of a Parameterized class can be queried using the
Parameterized.param.outputs method. By default the output will
inherit the method name but a custom name can be declared by
expressing the Parameter type using a keyword argument.
The simplest declaration simply declares the method returns an
object without any type guarantees, e.g.:
@output()
If a specific parameter type is specified this is a declaration
that the method will return a value of that type, e.g.:
@output(param.Number())
To override the default name of the output the type may be declared
as a keyword argument, e.g.:
@output(custom_name=param.Number())
Multiple outputs may be declared using keywords mapping from output name
to the type or using tuples of the same format, i.e. these two declarations
are equivalent:
@output(number=param.Number(), string=param.String())
@output(('number', param.Number()), ('string', param.String()))
output also accepts Python object types which will be upgraded to
a ClassSelector, e.g.:
@output(int)
"""
if output:
outputs = []
for i, out in enumerate(output):
i = i if len(output) > 1 else None
if isinstance(out, tuple) and len(out) == 2 and isinstance(out[0], str):
outputs.append(out+(i,))
elif isinstance(out, str):
outputs.append((out, Parameter(), i))
else:
outputs.append((None, out, i))
elif kw:
# (requires keywords to be kept ordered, which was not true in previous versions)
outputs = [(name, otype, i if len(kw) > 1 else None)
for i, (name, otype) in enumerate(kw.items())]
else:
outputs = [(None, Parameter(), None)]
names, processed = [], []
for name, otype, i in outputs:
if isinstance(otype, type):
if issubclass(otype, Parameter):
otype = otype()
else:
from .import ClassSelector
otype = ClassSelector(class_=otype)
elif isinstance(otype, tuple) and all(isinstance(t, type) for t in otype):
from .import ClassSelector
otype = ClassSelector(class_=otype)
if not isinstance(otype, Parameter):
raise ValueError('output type must be declared with a Parameter class, '
'instance or a Python object type.')
processed.append((name, otype, i))
names.append(name)
if len(set(names)) != len(names):
raise ValueError('When declaring multiple outputs each value '
'must be unique.')
_dinfo = getattr(func, '_dinfo', {})
_dinfo.update({'outputs': processed})
@wraps(func)
def _output(*args,**kw):
return func(*args,**kw)
_output._dinfo = _dinfo
return _output
def _parse_dependency_spec(spec):
"""
Parses param.depends specifications into three components:
1. The dotted path to the sub-object
2. The attribute being depended on, i.e. either a parameter or method
3. The parameter attribute being depended on
"""
assert spec.count(":")<=1
spec = spec.strip()
m = re.match("(?P[^:]*):?(?P.*)", spec)
what = m.group('what')
path = "."+m.group('path')
m = re.match(r"(?P.*)(\.)(?P.*)", path)
obj = m.group('obj')
attr = m.group("attr")
return obj or None, attr, what or 'value'
def _params_depended_on(minfo, dynamic=True, intermediate=True):
"""
Resolves dependencies declared on a Parameterized method.
Dynamic dependencies, i.e. dependencies on sub-objects which may
or may not yet be available, are only resolved if dynamic=True.
By default intermediate dependencies, i.e. dependencies on the
path to a sub-object are returned. For example for a dependency
on 'a.b.c' dependencies on 'a' and 'b' are returned as long as
intermediate=True.
Returns lists of concrete dependencies on available parameters
and dynamic dependencies specifications which have to resolved
if the referenced sub-objects are defined.
"""
deps, dynamic_deps = [], []
dinfo = getattr(minfo.method, "_dinfo", {})
for d in dinfo.get('dependencies', list(minfo.cls.param)):
ddeps, ddynamic_deps = (minfo.cls if minfo.inst is None else minfo.inst).param._spec_to_obj(d, dynamic, intermediate)
dynamic_deps += ddynamic_deps
for dep in ddeps:
if isinstance(dep, PInfo):
deps.append(dep)
else:
method_deps, method_dynamic_deps = _params_depended_on(dep, dynamic, intermediate)
deps += method_deps
dynamic_deps += method_dynamic_deps
return deps, dynamic_deps
def _resolve_mcs_deps(obj, resolved, dynamic, intermediate=True):
"""
Resolves constant and dynamic parameter dependencies previously
obtained using the _params_depended_on function. Existing resolved
dependencies are updated with a supplied parameter instance while
dynamic dependencies are resolved if possible.
"""
dependencies = []
for dep in resolved:
if not issubclass(type(obj), dep.cls):
dependencies.append(dep)
continue
inst = obj if dep.inst is None else dep.inst
dep = PInfo(inst=inst, cls=dep.cls, name=dep.name,
pobj=inst.param[dep.name], what=dep.what)
dependencies.append(dep)
for dep in dynamic:
subresolved, _ = obj.param._spec_to_obj(dep.spec, intermediate=intermediate)
for subdep in subresolved:
if isinstance(subdep, PInfo):
dependencies.append(subdep)
else:
dependencies += _params_depended_on(subdep, intermediate=intermediate)[0]
return dependencies
def _skip_event(*events, **kwargs):
"""
Checks whether a subobject event should be skipped.
Returns True if all the values on the new subobject
match the values on the previous subobject.
"""
what = kwargs.get('what', 'value')
changed = kwargs.get('changed')
if changed is None:
return False
for e in events:
for p in changed:
if what == 'value':
old = Undefined if e.old is None else _getattrr(e.old, p, None)
new = Undefined if e.new is None else _getattrr(e.new, p, None)
else:
old = Undefined if e.old is None else _getattrr(e.old.param[p], what, None)
new = Undefined if e.new is None else _getattrr(e.new.param[p], what, None)
if not Comparator.is_equal(old, new):
return False
return True
def extract_dependencies(function):
"""
Extract references from a method or function that declares the references.
"""
subparameters = list(function._dinfo['dependencies'])+list(function._dinfo['kw'].values())
params = []
for p in subparameters:
if isinstance(p, str):
owner = get_method_owner(function)
*subps, p = p.split('.')
for subp in subps:
owner = getattr(owner, subp, None)
if owner is None:
raise ValueError('Cannot depend on undefined sub-parameter {p!r}.')
if p in owner.param:
pobj = owner.param[p]
if pobj not in params:
params.append(pobj)
else:
for sp in extract_dependencies(getattr(owner, p)):
if sp not in params:
params.append(sp)
elif p not in params:
params.append(p)
return params
# Two callers at the module top level to support pickling.
async def _async_caller(*events, what='value', changed=None, callback=None, function=None):
if callback:
callback(*events)
if not _skip_event or not _skip_event(*events, what=what, changed=changed):
await function()
def _sync_caller(*events, what='value', changed=None, callback=None, function=None):
if callback:
callback(*events)
if not _skip_event(*events, what=what, changed=changed):
return function()
def _m_caller(self, method_name, what='value', changed=None, callback=None):
"""
Wraps a method call adding support for scheduling a callback
before it is executed and skipping events if a subobject has
changed but its values have not.
"""
function = getattr(self, method_name)
_caller = _async_caller if iscoroutinefunction(function) else _sync_caller
caller = partial(_caller, what=what, changed=changed, callback=callback, function=function)
caller._watcher_name = method_name
return caller
def _add_doc(obj, docstring):
"""Add a docstring to a namedtuple"""
obj.__doc__ = docstring
PInfo = namedtuple("PInfo", "inst cls name pobj what")
_add_doc(PInfo,
"""
Object describing something being watched about a Parameter.
`inst`: Parameterized instance owning the Parameter, or None
`cls`: Parameterized class owning the Parameter
`name`: Name of the Parameter being watched
`pobj`: Parameter object being watched
`what`: What is being watched on the Parameter (either 'value' or a slot name)
""")
MInfo = namedtuple("MInfo", "inst cls name method")
_add_doc(MInfo,
"""
Object describing a Parameterized method being watched.
`inst`: Parameterized instance owning the method, or None
`cls`: Parameterized class owning the method
`name`: Name of the method being watched
`method`: bound method of the object being watched
""")
DInfo = namedtuple("DInfo", "spec")
_add_doc(DInfo,
"""
Object describing dynamic dependencies.
`spec`: Dependency specification to resolve
""")
Event = namedtuple("Event", "what name obj cls old new type")
_add_doc(Event,
"""
Object representing an event that triggers a Watcher.
`what`: What is being watched on the Parameter (either value or a slot name)
`name`: Name of the Parameter that was set or triggered
`obj`: Parameterized instance owning the watched Parameter, or None
`cls`: Parameterized class owning the watched Parameter
`old`: Previous value of the item being watched
`new`: New value of the item being watched
`type`: `triggered` if this event was triggered explicitly), `changed` if
the item was set and watching for `onlychanged`, `set` if the item was set,
or None if type not yet known
""")
_Watcher = namedtuple("Watcher", "inst cls fn mode onlychanged parameter_names what queued precedence")
class Watcher(_Watcher):
"""
Object declaring a callback function to invoke when an Event is
triggered on a watched item.
`inst`: Parameterized instance owning the watched Parameter, or
None
`cls`: Parameterized class owning the watched Parameter
`fn`: Callback function to invoke when triggered by a watched
Parameter
`mode`: 'args' for param.watch (call `fn` with PInfo object
positional args), or 'kwargs' for param.watch_values (call `fn`
with : keywords)
`onlychanged`: If True, only trigger for actual changes, not
setting to the current value
`parameter_names`: List of Parameters to watch, by name
`what`: What to watch on the Parameters (either 'value' or a slot
name)
`queued`: Immediately invoke callbacks triggered during processing
of an Event (if False), or queue them up for processing
later, after this event has been handled (if True)
`precedence`: A numeric value which determines the precedence of
the watcher. Lower precedence values are executed
with higher priority.
"""
def __new__(cls_, *args, **kwargs):
"""
Allows creating Watcher without explicit precedence value.
"""
values = dict(zip(cls_._fields, args))
values.update(kwargs)
if 'precedence' not in values:
values['precedence'] = 0
return super().__new__(cls_, **values)
def __str__(self):
cls = type(self)
attrs = ', '.join([f'{f}={getattr(self, f)!r}' for f in cls._fields])
return f"{cls.__name__}({attrs})"
class ParameterMetaclass(type):
"""
Metaclass allowing control over creation of Parameter classes.
"""
def __new__(mcs, classname, bases, classdict):
# store the class's docstring in __classdoc
if '__doc__' in classdict:
classdict['__classdoc']=classdict['__doc__']
# when asking for help on Parameter *object*, return the doc slot
classdict['__doc__'] = property(attrgetter('doc'))
# Compute all slots in order, using a dict later turned into a list
# as it's the fastest way to get an ordered set in Python
all_slots = {}
for bcls in set(chain(*(base.__mro__[::-1] for base in bases))):
all_slots.update(dict.fromkeys(getattr(bcls, '__slots__', [])))
# To get the benefit of slots, subclasses must themselves define
# __slots__, whether or not they define attributes not present in
# the base Parameter class. That's because a subclass will have
# a __dict__ unless it also defines __slots__.
if '__slots__' not in classdict:
classdict['__slots__'] = []
else:
all_slots.update(dict.fromkeys(classdict['__slots__']))
classdict['_all_slots_'] = list(all_slots)
# No special handling for a __dict__ slot; should there be?
return type.__new__(mcs, classname, bases, classdict)
def __getattribute__(mcs,name):
if name=='__doc__':
# when asking for help on Parameter *class*, return the
# stored class docstring
return type.__getattribute__(mcs,'__classdoc')
else:
return type.__getattribute__(mcs,name)
class _ParameterBase(metaclass=ParameterMetaclass):
"""
Base Parameter class used to dynamically update the signature of all
the Parameters.
"""
@classmethod
def _modified_slots_defaults(cls):
defaults = cls._slot_defaults.copy()
defaults['label'] = defaults.pop('_label')
return defaults
@classmethod
def __init_subclass__(cls):
# _update_signature has been tested against the Parameters available
# in Param, we don't want to break the Parameters created elsewhere
# so wrapping this in a loose try/except.
try:
cls._update_signature()
except Exception:
# The super signature has been changed so we need to get the one
# from the class constructor directly.
cls.__signature__ = inspect.signature(cls.__init__)
@classmethod
def _update_signature(cls):
defaults = cls._modified_slots_defaults()
new_parameters = {}
for i, kls in enumerate(cls.mro()):
if kls.__name__.startswith('_'):
continue
sig = inspect.signature(kls.__init__)
for pname, parameter in sig.parameters.items():
if pname == 'self':
continue
if i >= 1 and parameter.default == inspect.Signature.empty:
continue
if parameter.kind in (inspect.Parameter.VAR_KEYWORD, inspect.Parameter.VAR_POSITIONAL):
continue
if getattr(parameter, 'default', None) is Undefined:
if pname not in defaults:
raise LookupError(
f'Argument {pname!r} of Parameter {cls.__name__!r} has no '
'entry in _slot_defaults.'
)
default = defaults[pname]
if callable(default) and hasattr(default, 'sig'):
default = default.sig
new_parameter = parameter.replace(default=default)
else:
new_parameter = parameter
if i >= 1:
new_parameter = new_parameter.replace(kind=inspect.Parameter.KEYWORD_ONLY)
new_parameters.setdefault(pname, new_parameter)
def _sorter(p):
if p.default == inspect.Signature.empty:
return 0
else:
return 1
new_parameters = sorted(new_parameters.values(), key=_sorter)
new_sig = sig.replace(parameters=new_parameters)
cls.__signature__ = new_sig
class Parameter(_ParameterBase):
"""
An attribute descriptor for declaring parameters.
Parameters are a special kind of class attribute. Setting a
Parameterized class attribute to be a Parameter instance causes
that attribute of the class (and the class's instances) to be
treated as a Parameter. This allows special behavior, including
dynamically generated parameter values, documentation strings,
constant and read-only parameters, and type or range checking at
assignment time.
For example, suppose someone wants to define two new kinds of
objects Foo and Bar, such that Bar has a parameter delta, Foo is a
subclass of Bar, and Foo has parameters alpha, sigma, and gamma
(and delta inherited from Bar). She would begin her class
definitions with something like this::
class Bar(Parameterized):
delta = Parameter(default=0.6, doc='The difference between steps.')
...
class Foo(Bar):
alpha = Parameter(default=0.1, doc='The starting value.')
sigma = Parameter(default=0.5, doc='The standard deviation.',
constant=True)
gamma = Parameter(default=1.0, doc='The ending value.')
...
Class Foo would then have four parameters, with delta defaulting
to 0.6.
Parameters have several advantages over plain attributes:
1. Parameters can be set automatically when an instance is
constructed: The default constructor for Foo (and Bar) will
accept arbitrary keyword arguments, each of which can be used
to specify the value of a Parameter of Foo (or any of Foo's
superclasses). E.g., if a script does this::
myfoo = Foo(alpha=0.5)
myfoo.alpha will return 0.5, without the Foo constructor
needing special code to set alpha.
If Foo implements its own constructor, keyword arguments will
still be accepted if the constructor accepts a dictionary of
keyword arguments (as in ``def __init__(self,**params):``), and
then each class calls its superclass (as in
``super(Foo,self).__init__(**params)``) so that the
Parameterized constructor will process the keywords.
2. A Parameterized class need specify only the attributes of a
Parameter whose values differ from those declared in
superclasses; the other values will be inherited. E.g. if Foo
declares::
delta = Parameter(default=0.2)
the default value of 0.2 will override the 0.6 inherited from
Bar, but the doc will be inherited from Bar.
3. The Parameter descriptor class can be subclassed to provide
more complex behavior, allowing special types of parameters
that, for example, require their values to be numbers in
certain ranges, generate their values dynamically from a random
distribution, or read their values from a file or other
external source.
4. The attributes associated with Parameters provide enough
information for automatically generating property sheets in
graphical user interfaces, allowing Parameterized instances to
be edited by users.
Note that Parameters can only be used when set as class attributes
of Parameterized classes. Parameters used as standalone objects,
or as class attributes of non-Parameterized classes, will not have
the behavior described here.
"""
# Because they implement __get__ and __set__, Parameters are known
# as 'descriptors' in Python; see "Implementing Descriptors" and
# "Invoking Descriptors" in the 'Customizing attribute access'
# section of the Python reference manual:
# http://docs.python.org/ref/attribute-access.html
#
# Overview of Parameters for programmers
# ======================================
#
# Consider the following code:
#
#
# class A(Parameterized):
# p = Parameter(default=1)
#
# a1 = A()
# a2 = A()
#
#
# * a1 and a2 share one Parameter object (A.__dict__['p']).
#
# * The default (class) value of p is stored in this Parameter
# object (A.__dict__['p'].default).
#
# * If the value of p is set on a1 (e.g. a1.p=2), a1's value of p
# is stored in a1 itself (a1._param__private.values['p'])
#
# * When a1.p is requested, a1._param__private.values['p'] is
# returned. When a2.p is requested, 'p' is not found in
# a1._param__private.values, so A.__dict__['p'].default (i.e. A.p) is
# returned instead.
#
#
# Be careful when referring to the 'name' of a Parameter:
#
# * A Parameterized class has a name for the attribute which is
# being represented by the Parameter ('p' in the example above);
# in the code, this is called the 'name'.
#
# * When a Parameterized instance has its own local value for a
# parameter, it is stored as 'p._param__private.values[X]' where X is the
# name of the Parameter
# So that the extra features of Parameters do not require a lot of
# overhead, Parameters are implemented using __slots__ (see
# http://www.python.org/doc/2.4/ref/slots.html). Instead of having
# a full Python dictionary associated with each Parameter instance,
# Parameter instances have an enumerated list (named __slots__) of
# attributes, and reserve just enough space to store these
# attributes. Using __slots__ requires special support for
# operations to copy and restore Parameters (e.g. for Python
# persistent storage pickling); see __getstate__ and __setstate__.
__slots__ = ['name', 'default', 'doc',
'precedence', 'instantiate', 'constant', 'readonly',
'pickle_default_value', 'allow_None', 'per_instance',
'watchers', 'owner', 'allow_refs', 'nested_refs', '_label']
# Note: When initially created, a Parameter does not know which
# Parameterized class owns it, nor does it know its names
# (attribute name, internal name). Once the owning Parameterized
# class is created, owner, and name are
# set.
_serializers = {'json': serializer.JSONSerialization}
_slot_defaults = dict(
default=None, precedence=None, doc=None, _label=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, allow_None=False,
per_instance=True, allow_refs=False, nested_refs=False
)
# Parameters can be updated during Parameterized class creation when they
# are defined multiple times in a class hierarchy. We have to record which
# Parameter slots require the default value to be re-validated. Any slots
# in this list do not have to trigger such re-validation.
_non_validated_slots = ['_label', 'doc', 'name', 'precedence',
'constant', 'pickle_default_value',
'watchers', 'owner']
@typing.overload
def __init__(
self,
default=None, *,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, doc=Undefined, # pylint: disable-msg=R0913
label=Undefined, precedence=Undefined,
instantiate=Undefined, constant=Undefined, readonly=Undefined,
pickle_default_value=Undefined, allow_None=Undefined,
per_instance=Undefined, allow_refs=Undefined, nested_refs=Undefined):
"""Initialize a new Parameter object and store the supplied attributes:
default: the owning class's value for the attribute represented
by this Parameter, which can be overridden in an instance.
doc: docstring explaining what this parameter represents.
label: optional text label to be used when this Parameter is
shown in a listing. If no label is supplied, the attribute name
for this parameter in the owning Parameterized object is used.
precedence: a numeric value, usually in the range 0.0 to 1.0,
which allows the order of Parameters in a class to be defined in
a listing or e.g. in GUI menus. A negative precedence indicates
a parameter that should be hidden in such listings.
instantiate: controls whether the value of this Parameter will
be deepcopied when a Parameterized object is instantiated (if
True), or if the single default value will be shared by all
Parameterized instances (if False). For an immutable Parameter
value, it is best to leave instantiate at the default of
False, so that a user can choose to change the value at the
Parameterized instance level (affecting only that instance) or
at the Parameterized class or superclass level (affecting all
existing and future instances of that class or superclass). For
a mutable Parameter value, the default of False is also appropriate
if you want all instances to share the same value state, e.g. if
they are each simply referring to a single global object like
a singleton. If instead each Parameterized should have its own
independently mutable value, instantiate should be set to
True, but note that there is then no simple way to change the
value of this Parameter at the class or superclass level,
because each instance, once created, will then have an
independently instantiated value.
constant: if true, the Parameter value can be changed only at
the class level or in a Parameterized constructor call. The
value is otherwise constant on the Parameterized instance,
once it has been constructed.
readonly: if true, the Parameter value cannot ordinarily be
changed by setting the attribute at the class or instance
levels at all. The value can still be changed in code by
temporarily overriding the value of this slot and then
restoring it, which is useful for reporting values that the
_user_ should never change but which do change during code
execution.
pickle_default_value: whether the default value should be
pickled. Usually, you would want the default value to be pickled,
but there are rare cases where that would not be the case (e.g.
for file search paths that are specific to a certain system).
per_instance: whether a separate Parameter instance will be
created for every Parameterized instance. True by default.
If False, all instances of a Parameterized class will share
the same Parameter object, including all validation
attributes (bounds, etc.). See also instantiate, which is
conceptually similar but affects the Parameter value rather
than the Parameter object.
allow_None: if True, None is accepted as a valid value for
this Parameter, in addition to any other values that are
allowed. If the default value is defined as None, allow_None
is set to True automatically.
allow_refs: if True allows automatically linking parameter
references to this Parameter, i.e. the parameter value will
automatically reflect the current value of the reference that
is passed in.
nested_refs: if True and allow_refs=True then even nested objects
such as dictionaries, lists, slices, tuples and sets will be
inspected for references and will be automatically resolved.
default, doc, and precedence all default to None, which allows
inheritance of Parameter slots (attributes) from the owning-class'
class hierarchy (see ParameterizedMetaclass).
"""
self.name = None
self.owner = None
self.allow_refs = allow_refs
self.nested_refs = nested_refs
self.precedence = precedence
self.default = default
self.doc = doc
self.constant = constant is True or readonly is True # readonly => constant
self.readonly = readonly
self._label = label
self._set_instantiate(instantiate)
self.pickle_default_value = pickle_default_value
self._set_allow_None(allow_None)
self.watchers = {}
self.per_instance = per_instance
@classmethod
def serialize(cls, value):
"Given the parameter value, return a Python value suitable for serialization"
return value
@classmethod
def deserialize(cls, value):
"Given a serializable Python value, return a value that the parameter can be set to"
return value
def schema(self, safe=False, subset=None, mode='json'):
if serializer is None:
raise ImportError('Cannot import serializer.py needed to generate schema')
if mode not in self._serializers:
raise KeyError(f'Mode {mode!r} not in available serialization formats {list(self._serializers.keys())!r}')
return self._serializers[mode].param_schema(self.__class__.__name__, self,
safe=safe, subset=subset)
@property
def rx(self):
from .reactive import reactive_ops
return reactive_ops(self)
@property
def label(self):
if self.name and self._label is None:
return label_formatter(self.name)
else:
return self._label
@label.setter
def label(self, val):
self._label = val
def _set_allow_None(self, allow_None):
# allow_None is set following these rules (last takes precedence):
# 1. to False by default
# 2. to the value provided in the constructor, if any
# 3. to True if default is None
if self.default is None:
self.allow_None = True
elif allow_None is not Undefined:
self.allow_None = allow_None
else:
self.allow_None = self._slot_defaults['allow_None']
def _set_instantiate(self,instantiate):
"""Constant parameters must be instantiated."""
# instantiate doesn't actually matter for read-only
# parameters, since they can't be set even on a class. But
# having this code avoids needless instantiation.
if self.readonly:
self.instantiate = False
elif instantiate is not Undefined:
self.instantiate = instantiate
else:
# Default value
self.instantiate = self._slot_defaults['instantiate']
def __setattr__(self, attribute, value):
if attribute == 'name':
name = getattr(self, 'name', None)
if name is not None and value != name:
raise AttributeError("Parameter name cannot be modified after "
"it has been bound to a Parameterized.")
is_slot = attribute in self.__class__._all_slots_
has_watcher = attribute != "default" and attribute in getattr(self, 'watchers', [])
if not (is_slot or has_watcher):
# Return early if attribute is not a slot
return super().__setattr__(attribute, value)
# Otherwise get the old value so we can call watcher/on_set
old = getattr(self, attribute, NotImplemented)
if is_slot:
try:
self._on_set(attribute, old, value)
except AttributeError:
pass
super().__setattr__(attribute, value)
if has_watcher and old is not NotImplemented:
self._trigger_event(attribute, old, value)
def _trigger_event(self, attribute, old, new):
event = Event(what=attribute, name=self.name, obj=None, cls=self.owner,
old=old, new=new, type=None)
for watcher in self.watchers[attribute]:
self.owner.param._call_watcher(watcher, event)
if not self.owner.param._BATCH_WATCH:
self.owner.param._batch_call_watchers()
def __getattribute__(self, key):
"""
Allow slot values to be Undefined in an "unbound" parameter, i.e. one
that is not (yet) owned by a Parameterized object, in which case their
value will be retrieved from the _slot_defaults dictionary.
"""
v = object.__getattribute__(self, key)
# Safely checks for name (avoiding recursion) to decide if this object is unbound
if v is Undefined and key != "name" and getattr(self, "name", None) is None:
try:
v = self._slot_defaults[key]
except KeyError as e:
raise KeyError(
f'Slot {key!r} on unbound parameter {self.__class__.__name__!r} '
'has no default value defined in `_slot_defaults`'
) from e
if callable(v):
v = v(self)
return v
def _on_set(self, attribute, old, value):
"""
Can be overridden on subclasses to handle changes when parameter
attribute is set.
"""
def _update_state(self):
"""
Can be overridden on subclasses to update a Parameter state, i.e. slot
values, after the slot values have been set in the inheritance procedure.
"""
def __get__(self, obj, objtype): # pylint: disable-msg=W0613
"""
Return the value for this Parameter.
If called for a Parameterized class, produce that
class's value (i.e. this Parameter object's 'default'
attribute).
If called for a Parameterized instance, produce that
instance's value, if one has been set - otherwise produce the
class's value (default).
"""
if obj is None: # e.g. when __get__ called for a Parameterized class
result = self.default
else:
# Attribute error when .values does not exist (_ClassPrivate)
# and KeyError when there's no cached value for this parameter.
try:
result = obj._param__private.values[self.name]
except (AttributeError, KeyError):
result = self.default
return result
@instance_descriptor
def __set__(self, obj, val):
"""
Set the value for this Parameter.
If called for a Parameterized class, set that class's
value (i.e. set this Parameter object's 'default' attribute).
If called for a Parameterized instance, set the value of
this Parameter on that instance (i.e. in the instance's
`values` dictionary located in the private namespace `_param__private`,
under the parameter's name).
If the Parameter's constant attribute is True, only allows
the value to be set for a Parameterized class or on
uninitialized Parameterized instances.
If the Parameter's readonly attribute is True, only allows the
value to be specified in the Parameter declaration inside the
Parameterized source code. A read-only parameter also
cannot be set on a Parameterized class.
Note that until we support some form of read-only
object, it is still possible to change the attributes of the
object stored in a constant or read-only Parameter (e.g. one
item in a list).
"""
name = self.name
if obj is not None and self.allow_refs and obj._param__private.initialized:
syncing = name in obj._param__private.syncing
ref, deps, val, is_async = obj.param._resolve_ref(self, val)
refs = obj._param__private.refs
if ref is not None:
self.owner.param._update_ref(name, ref)
elif name in refs and not syncing:
del refs[name]
if name in obj._param__private.async_refs:
obj._param__private.async_refs.pop(name).cancel()
if is_async or val is Undefined:
return
# Deprecated Number set_hook called here to avoid duplicating setter
if hasattr(self, 'set_hook'):
val = self.set_hook(obj, val)
if self.set_hook is not _identity_hook:
# PARAM3_DEPRECATION
warnings.warn(
'Number.set_hook has been deprecated.',
category=_ParamDeprecationWarning,
stacklevel=6,
)
self._validate(val)
_old = NotImplemented
# obj can be None if __set__ is called for a Parameterized class
if self.constant or self.readonly:
if self.readonly:
raise TypeError("Read-only parameter '%s' cannot be modified" % name)
elif obj is None:
_old = self.default
self.default = val
elif not obj._param__private.initialized:
_old = obj._param__private.values.get(self.name, self.default)
obj._param__private.values[self.name] = val
else:
_old = obj._param__private.values.get(self.name, self.default)
if val is not _old:
raise TypeError("Constant parameter '%s' cannot be modified" % name)
else:
if obj is None:
_old = self.default
self.default = val
else:
# When setting a Parameter before calling super.
if not isinstance(obj._param__private, _InstancePrivate):
obj._param__private = _InstancePrivate(
explicit_no_refs=type(obj)._param__private.explicit_no_refs
)
_old = obj._param__private.values.get(name, self.default)
obj._param__private.values[name] = val
self._post_setter(obj, val)
if obj is not None:
if not hasattr(obj, '_param__private') or not getattr(obj._param__private, 'initialized', False):
return
obj.param._update_deps(name)
if obj is None:
watchers = self.watchers.get("value")
elif name in obj._param__private.watchers:
watchers = obj._param__private.watchers[name].get('value')
if watchers is None:
watchers = self.watchers.get("value")
else:
watchers = None
obj = self.owner if obj is None else obj
if obj is None or not watchers:
return
event = Event(what='value', name=name, obj=obj, cls=self.owner,
old=_old, new=val, type=None)
# Copy watchers here since they may be modified inplace during iteration
for watcher in sorted(watchers, key=lambda w: w.precedence):
obj.param._call_watcher(watcher, event)
if not obj.param._BATCH_WATCH:
obj.param._batch_call_watchers()
def _validate_value(self, value, allow_None):
"""Implements validation for parameter value"""
def _validate(self, val):
"""Implements validation for the parameter value and attributes"""
self._validate_value(val, self.allow_None)
def _post_setter(self, obj, val):
"""Called after the parameter value has been validated and set"""
def __delete__(self,obj):
raise TypeError("Cannot delete '%s': Parameters deletion not allowed." % self.name)
def _set_names(self, attrib_name):
if None not in (self.owner, self.name) and attrib_name != self.name:
raise AttributeError('The {} parameter {!r} has already been '
'assigned a name by the {} class, '
'could not assign new name {!r}. Parameters '
'may not be shared by multiple classes; '
'ensure that you create a new parameter '
'instance for each new class.'.format(type(self).__name__, self.name,
self.owner.name, attrib_name))
self.name = attrib_name
def __getstate__(self):
"""
All Parameters have slots, not a dict, so we have to support
pickle and deepcopy ourselves.
"""
return {slot: getattr(self, slot) for slot in self.__class__._all_slots_}
def __setstate__(self,state):
# set values of __slots__ (instead of in non-existent __dict__)
for k, v in state.items():
setattr(self, k, v)
# Define one particular type of Parameter that is used in this file
class String(Parameter):
r"""
A String Parameter, with a default value and optional regular expression (regex) matching.
Example of using a regex to implement IPv4 address matching::
class IPAddress(String):
'''IPv4 address as a string (dotted decimal notation)'''
def __init__(self, default="0.0.0.0", allow_None=False, **kwargs):
ip_regex = r'^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$'
super(IPAddress, self).__init__(default=default, regex=ip_regex, **kwargs)
"""
__slots__ = ['regex']
_slot_defaults = _dict_update(Parameter._slot_defaults, default="", regex=None)
@typing.overload
def __init__(
self,
default="", *, regex=None,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, regex=Undefined, **kwargs):
super().__init__(default=default, **kwargs)
self.regex = regex
self._validate(self.default)
def _validate_regex(self, val, regex):
if (val is None and self.allow_None):
return
if regex is not None and re.match(regex, val) is None:
raise ValueError(
f'{_validate_error_prefix(self)} value {val!r} does not '
f'match regex {regex!r}.'
)
def _validate_value(self, val, allow_None):
if allow_None and val is None:
return
if not isinstance(val, str):
raise ValueError(
f'{_validate_error_prefix(self)} only takes a string value, '
f'not value of {type(val)}.'
)
def _validate(self, val):
self._validate_value(val, self.allow_None)
self._validate_regex(val, self.regex)
class shared_parameters:
"""
Context manager to share parameter instances when creating
multiple Parameterized objects of the same type. Parameter default
values are instantiated once and cached to be reused when another
Parameterized object of the same type is instantiated.
Can be useful to easily modify large collections of Parameterized
objects at once and can provide a significant speedup.
"""
_share = False
_shared_cache = {}
def __enter__(self):
shared_parameters._share = True
def __exit__(self, exc_type, exc_val, exc_tb):
shared_parameters._share = False
shared_parameters._shared_cache = {}
def as_uninitialized(fn):
"""
Decorator: call fn with the parameterized_instance's
initialization flag set to False, then revert the flag.
(Used to decorate Parameterized methods that must alter
a constant Parameter.)
"""
@wraps(fn)
def override_initialization(self_,*args,**kw):
parameterized_instance = self_.self
original_initialized = parameterized_instance._param__private.initialized
parameterized_instance._param__private.initialized = False
ret = fn(self_, *args, **kw)
parameterized_instance._param__private.initialized = original_initialized
return ret
return override_initialization
class Comparator:
"""
Comparator defines methods for determining whether two objects
should be considered equal. It works by registering custom
comparison functions, which may either be registed by type or with
a predicate function. If no matching comparison can be found for
the two objects the comparison will return False.
If registered by type the Comparator will check whether both
objects are of that type and apply the comparison. If the equality
function is instead registered with a function it will call the
function with each object individually to check if the comparison
applies. This is useful for defining comparisons for objects
without explicitly importing them.
To use the Comparator simply call the is_equal function.
"""
equalities = {
numbers.Number: operator.eq,
str: operator.eq,
bytes: operator.eq,
type(None): operator.eq,
lambda o: hasattr(o, '_infinitely_iterable'): operator.eq, # Time
}
equalities.update({dtt: operator.eq for dtt in dt_types})
@classmethod
def is_equal(cls, obj1, obj2):
for eq_type, eq in cls.equalities.items():
try:
are_instances = isinstance(obj1, eq_type) and isinstance(obj2, eq_type)
except TypeError:
pass
else:
if are_instances:
return eq(obj1, obj2)
if isinstance(eq_type, FunctionType) and eq_type(obj1) and eq_type(obj2):
return eq(obj1, obj2)
if isinstance(obj2, (list, set, tuple)):
return cls.compare_iterator(obj1, obj2)
elif isinstance(obj2, dict):
return cls.compare_mapping(obj1, obj2)
return False
@classmethod
def compare_iterator(cls, obj1, obj2):
if type(obj1) != type(obj2) or len(obj1) != len(obj2):
return False
for o1, o2 in zip(obj1, obj2):
if not cls.is_equal(o1, o2):
return False
return True
@classmethod
def compare_mapping(cls, obj1, obj2):
if type(obj1) != type(obj2) or len(obj1) != len(obj2): return False
for k in obj1:
if k in obj2:
if not cls.is_equal(obj1[k], obj2[k]):
return False
else:
return False
return True
class _ParametersRestorer:
"""
Context-manager to handle the reset of parameter values after an update.
"""
def __init__(self, *, parameters, restore, refs=None):
self._parameters = parameters
self._restore = restore
self._refs = {} if refs is None else refs
def __enter__(self):
return self._restore
def __exit__(self, exc_type, exc_value, exc_tb):
try:
self._parameters._update(dict(self._restore, **self._refs))
finally:
self._restore = {}
class Parameters:
"""Object that holds the namespace and implementation of Parameterized
methods as well as any state that is not in __slots__ or the
Parameters themselves.
Exists at both the metaclass level (instantiated by the metaclass)
and at the instance level. Can contain state specific to either the
class or the instance as necessary.
"""
def __init__(self_, cls, self=None):
"""
cls is the Parameterized class which is always set.
self is the instance if set.
"""
self_.cls = cls
self_.self = self
@property
def _BATCH_WATCH(self_):
return self_.self_or_cls._param__private.parameters_state['BATCH_WATCH']
@_BATCH_WATCH.setter
def _BATCH_WATCH(self_, value):
self_.self_or_cls._param__private.parameters_state['BATCH_WATCH'] = value
@property
def _TRIGGER(self_):
return self_.self_or_cls._param__private.parameters_state['TRIGGER']
@_TRIGGER.setter
def _TRIGGER(self_, value):
self_.self_or_cls._param__private.parameters_state['TRIGGER'] = value
@property
def _events(self_):
return self_.self_or_cls._param__private.parameters_state['events']
@_events.setter
def _events(self_, value):
self_.self_or_cls._param__private.parameters_state['events'] = value
@property
def _state_watchers(self_):
return self_.self_or_cls._param__private.parameters_state['watchers']
@_state_watchers.setter
def _state_watchers(self_, value):
self_.self_or_cls._param__private.parameters_state['watchers'] = value
@property
def watchers(self_):
"""Dictionary of instance watchers."""
if self_.self is None:
raise TypeError('Accessing `.param.watchers` is only supported on a Parameterized instance, not class.')
return self_.self._param__private.watchers
@watchers.setter
def watchers(self_, value):
if self_.self is None:
raise TypeError('Setting `.param.watchers` is only supported on a Parameterized instance, not class.')
self_.self._param__private.watchers = value
@property
def self_or_cls(self_):
return self_.cls if self_.self is None else self_.self
def __setstate__(self, state):
# Set old parameters state on Parameterized.parameters_state
self_, cls = state.get('self'), state.get('cls')
self_or_cls = self_ if self_ is not None else cls
for k in self_or_cls._param__private.parameters_state:
key = '_'+k
if key in state:
self_or_cls._param__private.parameters_state[k] = state.pop(key)
for k, v in state.items():
setattr(self, k, v)
def __getitem__(self_, key):
"""
Returns the class or instance parameter
"""
inst = self_.self
if inst is None:
return self_._cls_parameters[key]
p = self_.objects(instance=False)[key]
return _instantiated_parameter(inst, p)
def __dir__(self_):
"""
Adds parameters to dir
"""
return super().__dir__() + list(self_._cls_parameters)
def __iter__(self_):
"""
Iterates over the parameters on this object.
"""
yield from self_._cls_parameters
def __contains__(self_, param):
return param in self_._cls_parameters
def __getattr__(self_, attr):
"""
Extends attribute access to parameter objects.
"""
cls = self_.__dict__.get('cls')
if cls is None: # Class not initialized
raise AttributeError
if attr in self_._cls_parameters:
return self_.__getitem__(attr)
elif self_.self is None:
raise AttributeError(f"type object '{self_.cls.__name__}.param' has no attribute {attr!r}")
else:
raise AttributeError(f"'{self_.cls.__name__}.param' object has no attribute {attr!r}")
@as_uninitialized
def _set_name(self_, name):
self_.self.name = name
@as_uninitialized
def _generate_name(self_):
self_._set_name('%s%05d' % (self_.cls.__name__, object_count))
@as_uninitialized
def _setup_params(self_, **params):
"""
Initialize default and keyword parameter values.
First, ensures that values for all Parameters with 'instantiate=True'
(typically used for mutable Parameters) are copied directly into each object,
to ensure that there is an independent copy of the value (to avoid surprising
aliasing errors). Second, ensures that Parameters with 'constant=True' are
referenced on the instance, to make sure that setting a constant
Parameter on the class doesn't affect already created instances. Then
sets each of the keyword arguments, raising when any of them are not
defined as parameters.
"""
self = self_.self
## Deepcopy all 'instantiate=True' parameters
params_to_deepcopy = {}
params_to_ref = {}
objects = self_._cls_parameters
for pname, p in objects.items():
if p.instantiate and pname != "name":
params_to_deepcopy[pname] = p
elif p.constant and pname != 'name':
params_to_ref[pname] = p
for p in params_to_deepcopy.values():
self_._instantiate_param(p)
for p in params_to_ref.values():
self_._instantiate_param(p, deepcopy=False)
## keyword arg setting
deps, refs = {}, {}
for name, val in params.items():
desc = self_.cls.get_param_descriptor(name)[0] # pylint: disable-msg=E1101
if not desc:
raise TypeError(
f"{self.__class__.__name__}.__init__() got an unexpected "
f"keyword argument {name!r}"
)
pobj = objects.get(name)
if pobj is None or not pobj.allow_refs:
# Until Parameter.allow_refs=True by default we have to
# speculatively evaluate a values to check whether they
# contain a reference and warn the user that the
# behavior may change in future.
if name not in self_.cls._param__private.explicit_no_refs:
try:
ref, _, resolved, _ = self_._resolve_ref(pobj, val)
except Exception:
ref = None
if ref:
warnings.warn(
f"Parameter {name!r} on {pobj.owner} is being given a valid parameter "
f"reference {val} but is implicitly allow_refs=False. "
"In future allow_refs will be enabled by default and "
f"the reference {val} will be resolved to its underlying "
f"value {resolved}. Please explicitly set allow_ref on the "
"Parameter definition to declare whether references "
"should be resolved or not.",
category=_ParamFutureWarning,
stacklevel=4,
)
setattr(self, name, val)
continue
# Resolve references
ref, ref_deps, resolved, is_async = self_._resolve_ref(pobj, val)
if ref is not None:
refs[name] = ref
deps[name] = ref_deps
if not is_async and not (resolved is Undefined or resolved is Skip):
setattr(self, name, resolved)
return refs, deps
def _setup_refs(self_, refs):
groups = defaultdict(list)
for pname, subrefs in refs.items():
for p in subrefs:
if isinstance(p, Parameter):
groups[p.owner].append((pname, p.name))
else:
for sp in extract_dependencies(p):
groups[sp.owner].append((pname, sp.name))
for owner, pnames in groups.items():
refnames, pnames = zip(*pnames)
self_.self._param__private.ref_watchers.append((
refnames,
owner.param._watch(self_._sync_refs, list(set(pnames)), precedence=-1)
))
def _update_ref(self_, name, ref):
param_private = self_.self._param__private
if name in param_private.async_refs:
param_private.async_refs.pop(name).cancel()
for _, watcher in param_private.ref_watchers:
dep_obj = watcher.cls if watcher.inst is None else watcher.inst
dep_obj.param.unwatch(watcher)
self_.self._param__private.ref_watchers = []
refs = dict(self_.self._param__private.refs, **{name: ref})
deps = {name: resolve_ref(ref) for name, ref in refs.items()}
self_._setup_refs(deps)
self_.self._param__private.refs = refs
def _sync_refs(self_, *events):
updates = {}
for pname, ref in self_.self._param__private.refs.items():
# Skip updating value if dependency has not changed
recursive = self_[pname].nested_refs
deps = resolve_ref(ref, recursive)
is_gen = inspect.isgeneratorfunction(ref)
is_async = iscoroutinefunction(ref) or is_gen
if not any((dep.owner is e.obj and dep.name == e.name) for dep in deps for e in events) and not is_async:
continue
try:
new_val = resolve_value(ref, recursive)
except Skip:
new_val = Undefined
if new_val is Skip or new_val is Undefined:
continue
elif is_async:
async_executor(partial(self_._async_ref, pname, new_val))
continue
updates[pname] = new_val
with edit_constant(self_.self):
with _syncing(self_.self, updates):
self_.update(updates)
def _resolve_ref(self_, pobj, value):
is_gen = inspect.isgeneratorfunction(value)
is_async = iscoroutinefunction(value) or is_gen
deps = resolve_ref(value, recursive=pobj.nested_refs)
if not (deps or is_async or is_gen):
return None, None, value, False
ref = value
try:
value = resolve_value(value, recursive=pobj.nested_refs)
except Skip:
value = Undefined
if is_async:
async_executor(partial(self_._async_ref, pobj.name, value))
value = None
return ref, deps, value, is_async
async def _async_ref(self_, pname, awaitable):
if not self_.self._param__private.initialized:
async_executor(partial(self_._async_ref, pname, awaitable))
return
current_task = asyncio.current_task()
running_task = self_.self._param__private.async_refs.get(pname)
if running_task is None:
self_.self._param__private.async_refs[pname] = current_task
elif current_task is not running_task:
self_.self._param__private.async_refs[pname].cancel()
try:
if isinstance(awaitable, types.AsyncGeneratorType):
async for new_obj in awaitable:
with _syncing(self_.self, (pname,)):
self_.update({pname: new_obj})
else:
with _syncing(self_.self, (pname,)):
try:
self_.update({pname: await awaitable})
except Skip:
pass
finally:
# Ensure we clean up but only if the task matches the currrent task
if self_.self._param__private.async_refs.get(pname) is current_task:
del self_.self._param__private.async_refs[pname]
@classmethod
def _changed(cls, event):
"""
Predicate that determines whether a Event object has actually
changed such that old != new.
"""
return not Comparator.is_equal(event.old, event.new)
def _instantiate_param(self_, param_obj, dict_=None, key=None, deepcopy=True):
# deepcopy or store a reference to reference param_obj.default into
# self._param__private.values (or dict_ if supplied) under the
# parameter's name (or key if supplied)
instantiator = copy.deepcopy if deepcopy else lambda o: o
self = self_.self
dict_ = dict_ or self._param__private.values
key = key or param_obj.name
if shared_parameters._share:
param_key = (str(type(self)), param_obj.name)
if param_key in shared_parameters._shared_cache:
new_object = shared_parameters._shared_cache[param_key]
else:
new_object = instantiator(param_obj.default)
shared_parameters._shared_cache[param_key] = new_object
else:
new_object = instantiator(param_obj.default)
dict_[key] = new_object
if isinstance(new_object, Parameterized) and deepcopy:
global object_count
object_count += 1
# Writes over name given to the original object;
# could instead have kept the same name
new_object.param._generate_name()
def _update_deps(self_, attribute=None, init=False):
obj = self_.self
init_methods = []
for method, queued, on_init, constant, dynamic in type(obj).param._depends['watch']:
# On initialization set up constant watchers; otherwise
# clean up previous dynamic watchers for the updated attribute
dynamic = [d for d in dynamic if attribute is None or d.spec.split(".")[0] == attribute]
if init:
constant_grouped = defaultdict(list)
for dep in _resolve_mcs_deps(obj, constant, []):
constant_grouped[(id(dep.inst), id(dep.cls), dep.what)].append((None, dep))
for group in constant_grouped.values():
self_._watch_group(obj, method, queued, group)
m = getattr(self_.self, method)
if on_init and m not in init_methods:
init_methods.append(m)
elif dynamic:
for w in obj._param__private.dynamic_watchers.pop(method, []):
(w.cls if w.inst is None else w.inst).param.unwatch(w)
else:
continue
# Resolve dynamic dependencies one-by-one to be able to trace their watchers
grouped = defaultdict(list)
for ddep in dynamic:
for dep in _resolve_mcs_deps(obj, [], [ddep]):
grouped[(id(dep.inst), id(dep.cls), dep.what)].append((ddep, dep))
for group in grouped.values():
watcher = self_._watch_group(obj, method, queued, group, attribute)
obj._param__private.dynamic_watchers[method].append(watcher)
for m in init_methods:
m()
def _resolve_dynamic_deps(self, obj, dynamic_dep, param_dep, attribute):
"""
If a subobject whose parameters are being depended on changes
we should only trigger events if the actual parameter values
of the new object differ from those on the old subobject,
therefore we accumulate parameters to compare on a subobject
change event.
Additionally we need to make sure to notify the parent object
if a subobject changes so the dependencies can be
reinitialized so we return a callback which updates the
dependencies.
"""
subobj = obj
subobjs = [obj]
for subpath in dynamic_dep.spec.split('.')[:-1]:
subobj = getattr(subobj, subpath.split(':')[0], None)
subobjs.append(subobj)
dep_obj = param_dep.cls if param_dep.inst is None else param_dep.inst
if dep_obj not in subobjs[:-1]:
return None, None, param_dep.what
depth = subobjs.index(dep_obj)
callback = None
if depth > 0:
def callback(*events):
"""
If a subobject changes, we need to notify the main
object to update the dependencies.
"""
obj.param._update_deps(attribute)
p = '.'.join(dynamic_dep.spec.split(':')[0].split('.')[depth+1:])
if p == 'param':
subparams = [sp for sp in list(subobjs[-1].param)]
else:
subparams = [p]
if ':' in dynamic_dep.spec:
what = dynamic_dep.spec.split(':')[-1]
else:
what = param_dep.what
return subparams, callback, what
def _watch_group(self_, obj, name, queued, group, attribute=None):
"""
Sets up a watcher for a group of dependencies. Ensures that
if the dependency was dynamically generated we check whether
a subobject change event actually causes a value change and
that we update the existing watchers, i.e. clean up watchers
on the old subobject and create watchers on the new subobject.
"""
dynamic_dep, param_dep = group[0]
dep_obj = param_dep.cls if param_dep.inst is None else param_dep.inst
params = []
for _, g in group:
if g.name not in params:
params.append(g.name)
if dynamic_dep is None:
subparams, callback, what = None, None, param_dep.what
else:
subparams, callback, what = self_._resolve_dynamic_deps(
obj, dynamic_dep, param_dep, attribute)
mcaller = _m_caller(obj, name, what, subparams, callback)
return dep_obj.param._watch(
mcaller, params, param_dep.what, queued=queued, precedence=-1)
@_recursive_repr()
def _repr_html_(self_, open=True):
return _parameterized_repr_html(self_.self_or_cls, open)
# Classmethods
# PARAM3_DEPRECATION
@_deprecated(extra_msg="""Use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`""")
def print_param_defaults(self_):
"""Print the default values of all cls's Parameters.
.. deprecated:: 1.12.0
Use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
"""
cls = self_.cls
for key,val in cls.__dict__.items():
if isinstance(val,Parameter):
print(cls.__name__+'.'+key+ '='+ repr(val.default))
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `p.param.default =`")
def set_default(self_,param_name,value):
"""
Set the default value of param_name.
Equivalent to setting param_name on the class.
.. deprecated:: 1.12.0
Use instead `p.param.default =`
"""
cls = self_.cls
setattr(cls,param_name,value)
def add_parameter(self_, param_name, param_obj):
"""
Add a new Parameter object into this object's class.
Should result in a Parameter equivalent to one declared
in the class's source code.
"""
# Could have just done setattr(cls,param_name,param_obj),
# which is supported by the metaclass's __setattr__ , but
# would need to handle the params() cache as well
# (which is tricky but important for startup speed).
cls = self_.cls
type.__setattr__(cls, param_name, param_obj)
ParameterizedMetaclass._initialize_parameter(cls, param_name, param_obj)
# delete cached params()
cls._param__private.params.clear()
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `.param.add_parameter`")
def _add_parameter(self_,param_name, param_obj):
"""Add a new Parameter object into this object's class.
.. deprecated :: 1.12.0
"""
return self_.add_parameter(param_name, param_obj)
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `.param.values()` or `.param['param']`")
def params(self_, parameter_name=None):
"""
Return the Parameters of this class as the
dictionary {name: parameter_object}
Includes Parameters from this class and its
superclasses.
.. deprecated:: 1.12.0
Use instead `.param.values()` or `.param['param']`
"""
pdict = self_.objects(instance='existing')
if parameter_name is None:
return pdict
else:
return pdict[parameter_name]
# Bothmethods
def update(self_, arg=Undefined, /, **kwargs):
"""
For the given dictionary or iterable or set of param=value
keyword arguments, sets the corresponding parameter of this
object or class to the given value.
May also be used as a context manager to temporarily set and
then reset parameter values.
"""
refs = {}
if self_.self is not None:
private = self_.self._param__private
params = list(kwargs if arg is Undefined else dict(arg, **kwargs))
for pname in params:
if pname in refs:
continue
elif pname in private.refs:
refs[pname] = private.refs[pname]
elif pname in private.async_refs:
refs[pname] = private.async_refs[pname]
restore = dict(self_._update(arg, **kwargs))
return _ParametersRestorer(parameters=self_, restore=restore, refs=refs)
def _update(self_, arg=Undefined, /, **kwargs):
BATCH_WATCH = self_._BATCH_WATCH
self_._BATCH_WATCH = True
self_or_cls = self_.self_or_cls
if arg is not Undefined:
kwargs = dict(arg, **kwargs)
trigger_params = [
k for k in kwargs
if k in self_ and hasattr(self_[k], '_autotrigger_value')
]
for tp in trigger_params:
self_[tp]._mode = 'set'
values = self_.values()
restore = {k: values[k] for k, v in kwargs.items() if k in values}
for (k, v) in kwargs.items():
if k not in self_:
self_._BATCH_WATCH = False
raise ValueError(f"{k!r} is not a parameter of {self_.cls.__name__}")
try:
setattr(self_or_cls, k, v)
except:
self_._BATCH_WATCH = False
raise
self_._BATCH_WATCH = BATCH_WATCH
if not BATCH_WATCH:
self_._batch_call_watchers()
for tp in trigger_params:
p = self_[tp]
p._mode = 'reset'
setattr(self_or_cls, tp, p._autotrigger_reset_value)
p._mode = 'set-reset'
return restore
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `.param.update`")
def set_param(self_, *args,**kwargs):
"""
For each param=value keyword argument, sets the corresponding
parameter of this object or class to the given value.
For backwards compatibility, also accepts
set_param("param",value) for a single parameter value using
positional arguments, but the keyword interface is preferred
because it is more compact and can set multiple values.
.. deprecated:: 1.12.0
Use instead `.param.update`
"""
self_or_cls = self_.self_or_cls
if args:
if len(args) == 2 and not args[0] in kwargs and not kwargs:
kwargs[args[0]] = args[1]
else:
raise ValueError("Invalid positional arguments for %s.set_param" %
(self_or_cls.name))
return self_.update(kwargs)
@property
def _cls_parameters(self_):
"""
Class parameters are cached because they are accessed often,
and parameters are rarely added (and cannot be deleted)
"""
cls = self_.cls
pdict = cls._param__private.params
if pdict:
return pdict
paramdict = {}
for class_ in classlist(cls):
for name, val in class_.__dict__.items():
if isinstance(val, Parameter):
paramdict[name] = val
# We only want the cache to be visible to the cls on which
# params() is called, so we mangle the name ourselves at
# runtime (if we were to mangle it now, it would be
# _Parameterized.__params for all classes).
# cls._param__private.params[f'_{cls.__name__}__params'] = paramdict
cls._param__private.params = paramdict
return paramdict
def objects(self_, instance=True):
"""
Returns the Parameters of this instance or class
If instance=True and called on a Parameterized instance it
will create instance parameters for all Parameters defined on
the class. To force class parameters to be returned use
instance=False. Since classes avoid creating instance
parameters unless necessary you may also request only existing
instance parameters to be returned by setting
instance='existing'.
"""
if self_.self is not None and not self_.self._param__private.initialized and instance is True:
warnings.warn(
'Looking up instance Parameter objects (`.param.objects()`) until '
'the Parameterized instance has been fully initialized is deprecated and will raise an error in a future version. '
'Ensure you have called `super().__init__(**params)` in your Parameterized '
'constructor before trying to access instance Parameter objects, or '
'looking up the class Parameter objects with `.param.objects(instance=False)` '
'may be enough for your use case.',
category=_ParamFutureWarning,
stacklevel=2,
)
pdict = self_._cls_parameters
if instance and self_.self is not None:
if instance == 'existing':
if getattr(self_.self._param__private, 'initialized', False) and self_.self._param__private.params:
return dict(pdict, **self_.self._param__private.params)
return pdict
else:
return {k: self_.self.param[k] for k in pdict}
return pdict
def trigger(self_, *param_names):
"""
Trigger watchers for the given set of parameter names. Watchers
will be triggered whether or not the parameter values have
actually changed. As a special case, the value will actually be
changed for a Parameter of type Event, setting it to True so
that it is clear which Event parameter has been triggered.
"""
if self_.self is not None and not self_.self._param__private.initialized:
warnings.warn(
'Triggering watchers on a partially initialized Parameterized instance '
'is deprecated and will raise an error in a future version. '
'Ensure you have called super().__init__(**params) in '
'the Parameterized instance constructor before trying to set up a watcher.',
category=_ParamFutureWarning,
stacklevel=2,
)
trigger_params = [p for p in self_
if hasattr(self_[p], '_autotrigger_value')]
triggers = {p:self_[p]._autotrigger_value
for p in trigger_params if p in param_names}
events = self_._events
watchers = self_._state_watchers
self_._events = []
self_._state_watchers = []
param_values = self_.values()
params = {name: param_values[name] for name in param_names}
self_._TRIGGER = True
self_.update(dict(params, **triggers))
self_._TRIGGER = False
self_._events += events
self_._state_watchers += watchers
def _update_event_type(self_, watcher, event, triggered):
"""
Returns an updated Event object with the type field set appropriately.
"""
if triggered:
event_type = 'triggered'
else:
event_type = 'changed' if watcher.onlychanged else 'set'
return Event(what=event.what, name=event.name, obj=event.obj, cls=event.cls,
old=event.old, new=event.new, type=event_type)
def _execute_watcher(self, watcher, events):
if watcher.mode == 'args':
args, kwargs = events, {}
else:
args, kwargs = (), {event.name: event.new for event in events}
if iscoroutinefunction(watcher.fn):
if async_executor is None:
raise RuntimeError("Could not execute %s coroutine function. "
"Please register a asynchronous executor on "
"param.parameterized.async_executor, which "
"schedules the function on an event loop." %
watcher.fn)
async_executor(partial(watcher.fn, *args, **kwargs))
else:
try:
watcher.fn(*args, **kwargs)
except Skip:
pass
def _call_watcher(self_, watcher, event):
"""
Invoke the given watcher appropriately given an Event object.
"""
if self_._TRIGGER:
pass
elif watcher.onlychanged and (not self_._changed(event)):
return
if self_._BATCH_WATCH:
self_._events.append(event)
if not any(watcher is w for w in self_._state_watchers):
self_._state_watchers.append(watcher)
else:
event = self_._update_event_type(watcher, event, self_._TRIGGER)
with _batch_call_watchers(self_.self_or_cls, enable=watcher.queued, run=False):
self_._execute_watcher(watcher, (event,))
def _batch_call_watchers(self_):
"""
Batch call a set of watchers based on the parameter value
settings in kwargs using the queued Event and watcher objects.
"""
while self_._events:
event_dict = OrderedDict([((event.name, event.what), event)
for event in self_._events])
watchers = self_._state_watchers[:]
self_._events = []
self_._state_watchers = []
for watcher in sorted(watchers, key=lambda w: w.precedence):
events = [self_._update_event_type(watcher, event_dict[(name, watcher.what)],
self_._TRIGGER)
for name in watcher.parameter_names
if (name, watcher.what) in event_dict]
with _batch_call_watchers(self_.self_or_cls, enable=watcher.queued, run=False):
self_._execute_watcher(watcher, events)
def set_dynamic_time_fn(self_,time_fn,sublistattr=None):
"""
Set time_fn for all Dynamic Parameters of this class or
instance object that are currently being dynamically
generated.
Additionally, sets _Dynamic_time_fn=time_fn on this class or
instance object, so that any future changes to Dynamic
Parmeters can inherit time_fn (e.g. if a Number is changed
from a float to a number generator, the number generator will
inherit time_fn).
If specified, sublistattr is the name of an attribute of this
class or instance that contains an iterable collection of
subobjects on which set_dynamic_time_fn should be called. If
the attribute sublistattr is present on any of the subobjects,
set_dynamic_time_fn() will be called for those, too.
"""
self_or_cls = self_.self_or_cls
self_or_cls._Dynamic_time_fn = time_fn
if isinstance(self_or_cls,type):
a = (None,self_or_cls)
else:
a = (self_or_cls,)
for n,p in self_or_cls.param.objects('existing').items():
if hasattr(p, '_value_is_dynamic'):
if p._value_is_dynamic(*a):
g = self_or_cls.param.get_value_generator(n)
g._Dynamic_time_fn = time_fn
if sublistattr:
try:
sublist = getattr(self_or_cls,sublistattr)
except AttributeError:
sublist = []
for obj in sublist:
obj.param.set_dynamic_time_fn(time_fn,sublistattr)
def serialize_parameters(self_, subset=None, mode='json'):
self_or_cls = self_.self_or_cls
if mode not in Parameter._serializers:
raise ValueError(f'Mode {mode!r} not in available serialization formats {list(Parameter._serializers.keys())!r}')
serializer = Parameter._serializers[mode]
return serializer.serialize_parameters(self_or_cls, subset=subset)
def serialize_value(self_, pname, mode='json'):
self_or_cls = self_.self_or_cls
if mode not in Parameter._serializers:
raise ValueError(f'Mode {mode!r} not in available serialization formats {list(Parameter._serializers.keys())!r}')
serializer = Parameter._serializers[mode]
return serializer.serialize_parameter_value(self_or_cls, pname)
def deserialize_parameters(self_, serialization, subset=None, mode='json'):
self_or_cls = self_.self_or_cls
serializer = Parameter._serializers[mode]
return serializer.deserialize_parameters(self_or_cls, serialization, subset=subset)
def deserialize_value(self_, pname, value, mode='json'):
self_or_cls = self_.self_or_cls
if mode not in Parameter._serializers:
raise ValueError(f'Mode {mode!r} not in available serialization formats {list(Parameter._serializers.keys())!r}')
serializer = Parameter._serializers[mode]
return serializer.deserialize_parameter_value(self_or_cls, pname, value)
def schema(self_, safe=False, subset=None, mode='json'):
"""
Returns a schema for the parameters on this Parameterized object.
"""
self_or_cls = self_.self_or_cls
if mode not in Parameter._serializers:
raise ValueError(f'Mode {mode!r} not in available serialization formats {list(Parameter._serializers.keys())!r}')
serializer = Parameter._serializers[mode]
return serializer.schema(self_or_cls, safe=safe, subset=subset)
# PARAM3_DEPRECATION
# same as values() but returns list, not dict
@_deprecated(extra_msg="""
Use `.param.values().items()` instead (or `.param.values()` for the
common case of `dict(....param.get_param_values())`)
""")
def get_param_values(self_, onlychanged=False):
"""
Return a list of name,value pairs for all Parameters of this
object.
When called on an instance with onlychanged set to True, will
only return values that are not equal to the default value
(onlychanged has no effect when called on a class).
.. deprecated:: 1.12.0
Use `.param.values().items()` instead (or `.param.values()` for the
common case of `dict(....param.get_param_values())`)
"""
vals = self_.values(onlychanged)
return [(k, v) for k, v in vals.items()]
def values(self_, onlychanged=False):
"""
Return a dictionary of name,value pairs for the Parameters of this
object.
When called on an instance with onlychanged set to True, will
only return values that are not equal to the default value
(onlychanged has no effect when called on a class).
"""
self_or_cls = self_.self_or_cls
vals = []
for name, val in self_or_cls.param.objects('existing').items():
value = self_or_cls.param.get_value_generator(name)
if name == 'name' and onlychanged and _is_auto_name(self_.cls.__name__, value):
continue
if not onlychanged or not Comparator.is_equal(value, val.default):
vals.append((name, value))
vals.sort(key=itemgetter(0))
return dict(vals)
def force_new_dynamic_value(self_, name): # pylint: disable-msg=E0213
"""
Force a new value to be generated for the dynamic attribute
name, and return it.
If name is not dynamic, its current value is returned
(i.e. equivalent to getattr(name).
"""
cls_or_slf = self_.self_or_cls
param_obj = cls_or_slf.param.objects('existing').get(name)
if not param_obj:
return getattr(cls_or_slf, name)
cls, slf = None, None
if isinstance(cls_or_slf,type):
cls = cls_or_slf
else:
slf = cls_or_slf
if not hasattr(param_obj,'_force'):
return param_obj.__get__(slf, cls)
else:
return param_obj._force(slf, cls)
def get_value_generator(self_,name): # pylint: disable-msg=E0213
"""
Return the value or value-generating object of the named
attribute.
For most parameters, this is simply the parameter's value
(i.e. the same as getattr()), but Dynamic parameters have
their value-generating object returned.
"""
cls_or_slf = self_.self_or_cls
param_obj = cls_or_slf.param.objects('existing').get(name)
if not param_obj:
value = getattr(cls_or_slf,name)
# CompositeParameter detected by being a Parameter and having 'attribs'
elif hasattr(param_obj,'attribs'):
value = [cls_or_slf.param.get_value_generator(a) for a in param_obj.attribs]
# not a Dynamic Parameter
elif not hasattr(param_obj,'_value_is_dynamic'):
value = getattr(cls_or_slf,name)
# Dynamic Parameter...
else:
# TODO: is this always an instance?
if isinstance(cls_or_slf, Parameterized) and name in cls_or_slf._param__private.values:
# dealing with object and it's been set on this object
value = cls_or_slf._param__private.values[name]
else:
# dealing with class or isn't set on the object
value = param_obj.default
return value
def inspect_value(self_,name): # pylint: disable-msg=E0213
"""
Return the current value of the named attribute without modifying it.
Same as getattr() except for Dynamic parameters, which have their
last generated value returned.
"""
cls_or_slf = self_.self_or_cls
param_obj = cls_or_slf.param.objects('existing').get(name)
if not param_obj:
value = getattr(cls_or_slf,name)
elif hasattr(param_obj,'attribs'):
value = [cls_or_slf.param.inspect_value(a) for a in param_obj.attribs]
elif not hasattr(param_obj,'_inspect'):
value = getattr(cls_or_slf,name)
else:
if isinstance(cls_or_slf,type):
value = param_obj._inspect(None,cls_or_slf)
else:
value = param_obj._inspect(cls_or_slf,None)
return value
def method_dependencies(self_, name, intermediate=False):
"""
Given the name of a method, returns a PInfo object for each dependency
of this method. See help(PInfo) for the contents of these objects.
By default intermediate dependencies on sub-objects are not
returned as these are primarily useful for internal use to
determine when a sub-object dependency has to be updated.
"""
method = getattr(self_.self_or_cls, name)
minfo = MInfo(cls=self_.cls, inst=self_.self, name=name,
method=method)
deps, dynamic = _params_depended_on(
minfo, dynamic=False, intermediate=intermediate)
if self_.self is None:
return deps
return _resolve_mcs_deps(
self_.self, deps, dynamic, intermediate=intermediate)
# PARAM3_DEPRECATION
@_deprecated(extra_msg='Use instead `.param.method_dependencies`')
def params_depended_on(self_, *args, **kwargs):
"""
Given the name of a method, returns a PInfo object for each dependency
of this method. See help(PInfo) for the contents of these objects.
By default intermediate dependencies on sub-objects are not
returned as these are primarily useful for internal use to
determine when a sub-object dependency has to be updated.
.. deprecated: 2.0.0
Use instead `.param.method_dependencies`
"""
return self_.method_dependencies(*args, **kwargs)
def outputs(self_):
"""
Returns a mapping between any declared outputs and a tuple
of the declared Parameter type, the output method, and the
index into the output if multiple outputs are returned.
"""
outputs = {}
for cls in classlist(self_.cls):
for name in dir(cls):
if name == '_param_watchers':
continue
method = getattr(self_.self_or_cls, name)
dinfo = getattr(method, '_dinfo', {})
if 'outputs' not in dinfo:
continue
for override, otype, idx in dinfo['outputs']:
if override is not None:
name = override
outputs[name] = (otype, method, idx)
return outputs
def _spec_to_obj(self_, spec, dynamic=True, intermediate=True):
"""
Resolves a dependency specification into lists of explicit
parameter dependencies and dynamic dependencies.
Dynamic dependencies are specifications to be resolved when
the sub-object whose parameters are being depended on is
defined.
During class creation dynamic=False which means sub-object
dependencies are not resolved. At instance creation and
whenever a sub-object is set on an object this method will be
invoked to determine whether the dependency is available.
For sub-object dependencies we also return dependencies for
every part of the path, e.g. for a dependency specification
like "a.b.c" we return dependencies for sub-object "a" and the
sub-sub-object "b" in addition to the dependency on the actual
parameter "c" on object "b". This is to ensure that if a
sub-object is swapped out we are notified and can update the
dynamic dependency to the new object. Even if a sub-object
dependency can only partially resolved, e.g. if object "a"
does not yet have a sub-object "b" we must watch for changes
to "b" on sub-object "a" in case such a subobject is put in "b".
"""
if isinstance(spec, Parameter):
inst = spec.owner if isinstance(spec.owner, Parameterized) else None
cls = spec.owner if inst is None else type(inst)
info = PInfo(inst=inst, cls=cls, name=spec.name,
pobj=spec, what='value')
return [] if intermediate == 'only' else [info], []
obj, attr, what = _parse_dependency_spec(spec)
if obj is None:
src = self_.self_or_cls
elif not dynamic:
return [], [DInfo(spec=spec)]
else:
if not hasattr(self_.self_or_cls, obj.split('.')[1]):
raise AttributeError(
f'Dependency {obj[1:]!r} could not be resolved, {self_.self_or_cls} '
f'has no parameter or attribute {obj.split(".")[1]!r}. Ensure '
'the object being depended on is declared before calling the '
'Parameterized constructor.'
)
src = _getattrr(self_.self_or_cls, obj[1::], None)
if src is None:
path = obj[1:].split('.')
deps = []
# Attempt to partially resolve subobject path to ensure
# that if a subobject is later updated making the full
# subobject path available we have to be notified and
# set up watchers
if len(path) >= 1 and intermediate:
sub_src = None
subpath = path
while sub_src is None and subpath:
subpath = subpath[:-1]
sub_src = _getattrr(self_.self_or_cls, '.'.join(subpath), None)
if subpath:
subdeps, _ = self_._spec_to_obj(
'.'.join(path[:len(subpath)+1]), dynamic, intermediate)
deps += subdeps
return deps, [] if intermediate == 'only' else [DInfo(spec=spec)]
cls, inst = (src, None) if isinstance(src, type) else (type(src), src)
if attr == 'param':
deps, dynamic_deps = self_._spec_to_obj(obj[1:], dynamic, intermediate)
for p in src.param:
param_deps, param_dynamic_deps = src.param._spec_to_obj(p, dynamic, intermediate)
deps += param_deps
dynamic_deps += param_dynamic_deps
return deps, dynamic_deps
elif attr in src.param:
info = PInfo(inst=inst, cls=cls, name=attr,
pobj=src.param[attr], what=what)
elif hasattr(src, attr):
attr_obj = getattr(src, attr)
if isinstance(attr_obj, Parameterized):
return [], []
elif isinstance(attr_obj, (FunctionType, MethodType)):
info = MInfo(inst=inst, cls=cls, name=attr,
method=attr_obj)
else:
raise AttributeError(f"Attribute {attr!r} could not be resolved on {src}.")
elif getattr(src, "abstract", None):
return [], [] if intermediate == 'only' else [DInfo(spec=spec)]
else:
raise AttributeError(f"Attribute {attr!r} could not be resolved on {src}.")
if obj is None or not intermediate:
return [info], []
deps, dynamic_deps = self_._spec_to_obj(obj[1:], dynamic, intermediate)
if intermediate != 'only':
deps.append(info)
return deps, dynamic_deps
def _register_watcher(self_, action, watcher, what='value'):
if self_.self is not None and not self_.self._param__private.initialized:
warnings.warn(
'(Un)registering a watcher on a partially initialized Parameterized instance '
'is deprecated and will raise an error in a future version. Ensure '
'you have called super().__init__(**) in the Parameterized instance '
'constructor before trying to set up a watcher.',
category=_ParamFutureWarning,
stacklevel=4,
)
parameter_names = watcher.parameter_names
for parameter_name in parameter_names:
if parameter_name not in self_.cls.param:
raise ValueError("{} parameter was not found in list of "
"parameters of class {}".format(parameter_name, self_.cls.__name__))
if self_.self is not None and what == "value":
watchers = self_.self._param__private.watchers
if parameter_name not in watchers:
watchers[parameter_name] = {}
if what not in watchers[parameter_name]:
watchers[parameter_name][what] = []
getattr(watchers[parameter_name][what], action)(watcher)
else:
watchers = self_[parameter_name].watchers
if what not in watchers:
watchers[what] = []
getattr(watchers[what], action)(watcher)
def watch(self_, fn, parameter_names, what='value', onlychanged=True, queued=False, precedence=0):
"""
Register the given callback function `fn` to be invoked for
events on the indicated parameters.
`what`: What to watch on each parameter; either the value (by
default) or else the indicated slot (e.g. 'constant').
`onlychanged`: By default, only invokes the function when the
watched item changes, but if `onlychanged=False` also invokes
it when the `what` item is set to its current value again.
`queued`: By default, additional watcher events generated
inside the callback fn are dispatched immediately, effectively
doing depth-first processing of Watcher events. However, in
certain scenarios, it is helpful to wait to dispatch such
downstream events until all events that triggered this watcher
have been processed. In such cases setting `queued=True` on
this Watcher will queue up new downstream events generated
during `fn` until `fn` completes and all other watchers
invoked by that same event have finished executing),
effectively doing breadth-first processing of Watcher events.
`precedence`: Declares a precedence level for the Watcher that
determines the priority with which the callback is executed.
Lower precedence levels are executed earlier. Negative
precedences are reserved for internal Watchers, i.e. those
set up by param.depends.
When the `fn` is called, it will be provided the relevant
Event objects as positional arguments, which allows it to
determine which of the possible triggering events occurred.
Returns a Watcher object.
See help(Watcher) and help(Event) for the contents of those objects.
"""
if precedence < 0:
raise ValueError("User-defined watch callbacks must declare "
"a positive precedence. Negative precedences "
"are reserved for internal Watchers.")
return self_._watch(fn, parameter_names, what, onlychanged, queued, precedence)
def _watch(self_, fn, parameter_names, what='value', onlychanged=True, queued=False, precedence=-1):
parameter_names = tuple(parameter_names) if isinstance(parameter_names, list) else (parameter_names,)
watcher = Watcher(inst=self_.self, cls=self_.cls, fn=fn, mode='args',
onlychanged=onlychanged, parameter_names=parameter_names,
what=what, queued=queued, precedence=precedence)
self_._register_watcher('append', watcher, what)
return watcher
def unwatch(self_, watcher):
"""
Remove the given Watcher object (from `watch` or `watch_values`) from this object's list.
"""
try:
self_._register_watcher('remove', watcher, what=watcher.what)
except Exception:
self_.warning(f'No such watcher {str(watcher)} to remove.')
def watch_values(self_, fn, parameter_names, what='value', onlychanged=True, queued=False, precedence=0):
"""
Easier-to-use version of `watch` specific to watching for changes in parameter values.
Only allows `what` to be 'value', and invokes the callback `fn` using keyword
arguments = rather than with a list of Event objects.
"""
if precedence < 0:
raise ValueError("User-defined watch callbacks must declare "
"a positive precedence. Negative precedences "
"are reserved for internal Watchers.")
assert what == 'value'
if isinstance(parameter_names, list):
parameter_names = tuple(parameter_names)
else:
parameter_names = (parameter_names,)
watcher = Watcher(inst=self_.self, cls=self_.cls, fn=fn,
mode='kwargs', onlychanged=onlychanged,
parameter_names=parameter_names, what=what,
queued=queued, precedence=precedence)
self_._register_watcher('append', watcher, what)
return watcher
# Instance methods
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `{k:v.default for k,v in p.param.objects().items()}`")
def defaults(self_):
"""
Return {parameter_name:parameter.default} for all non-constant
Parameters.
Note that a Parameter for which instantiate==True has its default
instantiated.
.. deprecated:: 1.12.0
Use instead `{k:v.default for k,v in p.param.objects().items()}`
"""
self = self_.self
d = {}
for param_name, param in self.param.objects('existing').items():
if param.constant:
pass
if param.instantiate:
self.param._instantiate_param(param, dict_=d, key=param_name)
d[param_name] = param.default
return d
# Designed to avoid any processing unless the print
# level is high enough, though not all callers of message(),
# verbose(), debug(), etc are taking advantage of this.
def __db_print(self_,level,msg,*args,**kw):
"""
Calls the logger returned by the get_logger() function,
prepending the result of calling dbprint_prefix() (if any).
See python's logging module for details.
"""
self_or_cls = self_.self_or_cls
if get_logger(name=self_or_cls.name).isEnabledFor(level):
if dbprint_prefix and callable(dbprint_prefix):
msg = dbprint_prefix() + ": " + msg # pylint: disable-msg=E1102
get_logger(name=self_or_cls.name).log(level, msg, *args, **kw)
# PARAM3_DEPRECATION
@_deprecated(extra_msg="""Use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`""")
def print_param_values(self_):
"""Print the values of all this object's Parameters.
.. deprecated:: 1.12.0
Use instead `for k,v in p.param.objects().items(): print(f"{p.__class__.name}.{k}={repr(v.default)}")`
"""
self = self_.self
for name, val in self.param.values().items():
print(f'{self.name}.{name} = {val}')
def warning(self_, msg,*args,**kw):
"""
Print msg merged with args as a warning, unless module variable
warnings_as_exceptions is True, then raise an Exception
containing the arguments.
See Python's logging module for details of message formatting.
"""
self_.log(WARNING, msg, *args, **kw)
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `.param.log(param.MESSAGE, ...)`")
def message(self_,msg,*args,**kw):
"""
Print msg merged with args as a message.
See Python's logging module for details of message formatting.
.. deprecated:: 1.12.0
Use instead `.param.log(param.MESSAGE, ...)`
"""
self_.__db_print(INFO,msg,*args,**kw)
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `.param.log(param.VERBOSE, ...)`")
def verbose(self_,msg,*args,**kw):
"""
Print msg merged with args as a verbose message.
See Python's logging module for details of message formatting.
.. deprecated:: 1.12.0
Use instead `.param.log(param.VERBOSE, ...)`
"""
self_.__db_print(VERBOSE,msg,*args,**kw)
# PARAM3_DEPRECATION
@_deprecated(extra_msg="Use instead `.param.log(param.DEBUG, ...)`")
def debug(self_,msg,*args,**kw):
"""
Print msg merged with args as a debugging statement.
See Python's logging module for details of message formatting.
.. deprecated:: 1.12.0
Use instead `.param.log(param.DEBUG, ...)`
"""
self_.__db_print(DEBUG,msg,*args,**kw)
def log(self_, level, msg, *args, **kw):
"""
Print msg merged with args as a message at the indicated logging level.
Logging levels include those provided by the Python logging module
plus VERBOSE, either obtained directly from the logging module like
`logging.INFO`, or from parameterized like `param.parameterized.INFO`.
Supported logging levels include (in order of severity)
DEBUG, VERBOSE, INFO, WARNING, ERROR, CRITICAL
See Python's logging module for details of message formatting.
"""
if level is WARNING:
if warnings_as_exceptions:
raise Exception("Warning: " + msg % args)
else:
global warning_count
warning_count+=1
self_.__db_print(level, msg, *args, **kw)
# Note that there's no _state_push method on the class, so
# dynamic parameters set on a class can't have state saved. This
# is because, to do this, _state_push() would need to be a
# @bothmethod, but that complicates inheritance in cases where we
# already have a _state_push() method.
# (isinstance(g,Parameterized) below is used to exclude classes.)
def _state_push(self_):
"""
Save this instance's state.
For Parameterized instances, this includes the state of
dynamically generated values.
Subclasses that maintain short-term state should additionally
save and restore that state using _state_push() and
_state_pop().
Generally, this method is used by operations that need to test
something without permanently altering the objects' state.
"""
self = self_.self_or_cls
if not isinstance(self, Parameterized):
raise NotImplementedError('_state_push is not implemented at the class level')
for pname, p in self.param.objects('existing').items():
g = self.param.get_value_generator(pname)
if hasattr(g,'_Dynamic_last'):
g._saved_Dynamic_last.append(g._Dynamic_last)
g._saved_Dynamic_time.append(g._Dynamic_time)
# CB: not storing the time_fn: assuming that doesn't
# change.
elif hasattr(g,'_state_push') and isinstance(g,Parameterized):
g._state_push()
def _state_pop(self_):
"""
Restore the most recently saved state.
See _state_push() for more details.
"""
self = self_.self_or_cls
if not isinstance(self, Parameterized):
raise NotImplementedError('_state_pop is not implemented at the class level')
for pname, p in self.param.objects('existing').items():
g = self.param.get_value_generator(pname)
if hasattr(g,'_Dynamic_last'):
g._Dynamic_last = g._saved_Dynamic_last.pop()
g._Dynamic_time = g._saved_Dynamic_time.pop()
elif hasattr(g,'_state_pop') and isinstance(g,Parameterized):
g._state_pop()
def pprint(self_, imports=None, prefix=" ", unknown_value='',
qualify=False, separator=""):
"""
(Experimental) Pretty printed representation that may be
evaluated with eval. See pprint() function for more details.
"""
self = self_.self_or_cls
if not isinstance(self, Parameterized):
raise NotImplementedError('pprint is not implemented at the class level')
# Wrapping the staticmethod _pprint with partial to pass `self` as the `_recursive_repr`
# decorator expects `self`` to be the pprinted object (not `self_`).
return partial(self_._pprint, self, imports=imports, prefix=prefix,
unknown_value=unknown_value, qualify=qualify, separator=separator)()
@staticmethod
@_recursive_repr()
def _pprint(self, imports=None, prefix=" ", unknown_value='',
qualify=False, separator=""):
if imports is None:
imports = [] # would have been simpler to use a set from the start
imports[:] = list(set(imports))
# Generate import statement
mod = self.__module__
bits = mod.split('.')
imports.append("import %s"%mod)
imports.append("import %s"%bits[0])
changed_params = self.param.values(onlychanged=script_repr_suppress_defaults)
values = self.param.values()
spec = getfullargspec(type(self).__init__)
if 'self' not in spec.args or spec.args[0] != 'self':
raise KeyError(f"'{type(self).__name__}.__init__.__signature__' must contain 'self' as its first Parameter.")
args = spec.args[1:]
if spec.defaults is not None:
posargs = spec.args[:-len(spec.defaults)]
kwargs = dict(zip(spec.args[-len(spec.defaults):], spec.defaults))
else:
posargs, kwargs = args, []
parameters = self.param.objects('existing')
ordering = sorted(
sorted(changed_params), # alphanumeric tie-breaker
key=lambda k: (- float('inf') # No precedence is lowest possible precendence
if parameters[k].precedence is None else
parameters[k].precedence))
arglist, keywords, processed = [], [], []
for k in args + ordering:
if k in processed: continue
# Suppresses automatically generated names.
if k == 'name' and (values[k] is not None
and re.match('^'+self.__class__.__name__+'[0-9]+$', values[k])):
continue
value = pprint(values[k], imports, prefix=prefix,settings=[],
unknown_value=unknown_value,
qualify=qualify) if k in values else None
if value is None:
if unknown_value is False:
raise Exception(f"{self.name}: unknown value of {k!r}")
elif unknown_value is None:
# i.e. suppress repr
continue
else:
value = unknown_value
# Explicit kwarg (unchanged, known value)
if (k in kwargs) and (k in values) and kwargs[k] == values[k]: continue
if k in posargs:
# value will be unknown_value unless k is a parameter
arglist.append(value)
elif (k in kwargs or
(hasattr(spec, 'varkw') and (spec.varkw is not None)) or
(hasattr(spec, 'keywords') and (spec.keywords is not None))):
# Explicit modified keywords or parameters in
# precendence order (if **kwargs present)
keywords.append(f'{k}={value}')
processed.append(k)
qualifier = mod + '.' if qualify else ''
arguments = arglist + keywords + (['**%s' % spec.varargs] if spec.varargs else [])
return qualifier + '{}({})'.format(self.__class__.__name__, (','+separator+prefix).join(arguments))
class ParameterizedMetaclass(type):
"""
The metaclass of Parameterized (and all its descendents).
The metaclass overrides type.__setattr__ to allow us to set
Parameter values on classes without overwriting the attribute
descriptor. That is, for a Parameterized class of type X with a
Parameter y, the user can type X.y=3, which sets the default value
of Parameter y to be 3, rather than overwriting y with the
constant value 3 (and thereby losing all other info about that
Parameter, such as the doc string, bounds, etc.).
The __init__ method is used when defining a Parameterized class,
usually when the module where that class is located is imported
for the first time. That is, the __init__ in this metaclass
initializes the *class* object, while the __init__ method defined
in each Parameterized class is called for each new instance of
that class.
Additionally, a class can declare itself abstract by having an
attribute __abstract set to True. The 'abstract' attribute can be
used to find out if a class is abstract or not.
"""
def __init__(mcs, name, bases, dict_):
"""
Initialize the class object (not an instance of the class, but
the class itself).
Initializes all the Parameters by looking up appropriate
default values (see __param_inheritance()) and setting
attrib_names (see _set_names()).
"""
type.__init__(mcs, name, bases, dict_)
# Compute which parameters explicitly do not support references
# This can be removed when Parameter.allow_refs=True by default.
explicit_no_refs = set()
for base in bases:
if issubclass(base, Parameterized):
explicit_no_refs |= set(base._param__private.explicit_no_refs)
_param__private = _ClassPrivate(explicit_no_refs=list(explicit_no_refs))
mcs._param__private = _param__private
mcs.__set_name(name, dict_)
mcs._param__parameters = Parameters(mcs)
# All objects (with their names) of type Parameter that are
# defined in this class
parameters = [(n, o) for (n, o) in dict_.items()
if isinstance(o, Parameter)]
for param_name,param in parameters:
mcs._initialize_parameter(param_name, param)
# retrieve depends info from methods and store more conveniently
dependers = [(n, m, m._dinfo) for (n, m) in dict_.items()
if hasattr(m, '_dinfo')]
# Resolve dependencies of current class
_watch = []
for name, method, dinfo in dependers:
watch = dinfo.get('watch', False)
on_init = dinfo.get('on_init', False)
minfo = MInfo(cls=mcs, inst=None, name=name,
method=method)
deps, dynamic_deps = _params_depended_on(minfo, dynamic=False)
if watch:
_watch.append((name, watch == 'queued', on_init, deps, dynamic_deps))
# Resolve dependencies in class hierarchy
_inherited = []
for cls in classlist(mcs)[:-1][::-1]:
if not hasattr(cls, '_param__parameters'):
continue
for dep in cls.param._depends['watch']:
method = getattr(mcs, dep[0], None)
dinfo = getattr(method, '_dinfo', {'watch': False})
if (not any(dep[0] == w[0] for w in _watch+_inherited)
and dinfo.get('watch')):
_inherited.append(dep)
mcs.param._depends = {'watch': _inherited+_watch}
if docstring_signature:
mcs.__class_docstring()
def __set_name(mcs, name, dict_):
"""
Give Parameterized classes a useful 'name' attribute that is by
default the class name, unless a class in the hierarchy has defined
a `name` String Parameter with a defined `default` value, in which case
that value is used to set the class name.
"""
name_param = dict_.get("name", None)
if name_param is not None:
if not type(name_param) is String:
raise TypeError(
f"Parameterized class {name!r} cannot override "
f"the 'name' Parameter with type {type(name_param)}. "
"Overriding 'name' is only allowed with a 'String' Parameter."
)
if name_param.default:
mcs.name = name_param.default
mcs._param__private.renamed = True
else:
mcs.name = name
else:
classes = classlist(mcs)[::-1]
found_renamed = False
for c in classes:
if hasattr(c, '_param__private') and c._param__private.renamed:
found_renamed = True
break
if not found_renamed:
mcs.name = name
def __class_docstring(mcs):
"""
Customize the class docstring with a Parameter table if
`docstring_describe_params` and the `param_pager` is available.
"""
if not docstring_describe_params or not param_pager:
return
class_docstr = mcs.__doc__ if mcs.__doc__ else ''
description = param_pager(mcs)
mcs.__doc__ = class_docstr + '\n' + description
def _initialize_parameter(mcs, param_name, param):
# A Parameter has no way to find out the name a
# Parameterized class has for it
param._set_names(param_name)
mcs.__param_inheritance(param_name, param)
# Should use the official Python 2.6+ abstract base classes; see
# https://github.com/holoviz/param/issues/84
def __is_abstract(mcs):
"""
Return True if the class has an attribute __abstract set to True.
Subclasses will return False unless they themselves have
__abstract set to true. This mechanism allows a class to
declare itself to be abstract (e.g. to avoid it being offered
as an option in a GUI), without the "abstract" property being
inherited by its subclasses (at least one of which is
presumably not abstract).
"""
# Can't just do ".__abstract", because that is mangled to
# _ParameterizedMetaclass__abstract before running, but
# the actual class object will have an attribute
# _ClassName__abstract. So, we have to mangle it ourselves at
# runtime. Mangling follows description in
# https://docs.python.org/2/tutorial/classes.html#private-variables-and-class-local-references
try:
return getattr(mcs,'_%s__abstract'%mcs.__name__.lstrip("_"))
except AttributeError:
return False
def __get_signature(mcs):
"""
For classes with a constructor signature that matches the default
Parameterized.__init__ signature (i.e. ``__init__(self, **params)``)
this method will generate a new signature that expands the
parameters. If the signature differs from the default the
custom signature is returned.
"""
if mcs._param__private.signature:
return mcs._param__private.signature
# allowed_signature must be the signature of Parameterized.__init__
# Inspecting `mcs.__init__` instead of `mcs` to avoid a recursion error
if inspect.signature(mcs.__init__) != DEFAULT_SIGNATURE:
return None
processed_kws, keyword_groups = set(), []
for cls in reversed(mcs.mro()):
keyword_group = []
for k, v in sorted(cls.__dict__.items()):
if isinstance(v, Parameter) and k not in processed_kws and not v.readonly:
keyword_group.append(k)
processed_kws.add(k)
keyword_groups.append(keyword_group)
keywords = [el for grp in reversed(keyword_groups) for el in grp]
mcs._param__private.signature = signature = inspect.Signature([
inspect.Parameter(k, inspect.Parameter.KEYWORD_ONLY)
for k in keywords
])
return signature
__signature__ = property(__get_signature)
abstract = property(__is_abstract)
def _get_param(mcs):
return mcs._param__parameters
param = property(_get_param)
def __setattr__(mcs, attribute_name, value):
"""
Implements 'self.attribute_name=value' in a way that also supports Parameters.
If there is already a descriptor named attribute_name, and
that descriptor is a Parameter, and the new value is *not* a
Parameter, then call that Parameter's __set__ method with the
specified value.
In all other cases set the attribute normally (i.e. overwrite
the descriptor). If the new value is a Parameter, once it has
been set we make sure that the value is inherited from
Parameterized superclasses as described in __param_inheritance().
"""
# Find out if there's a Parameter called attribute_name as a
# class attribute of this class - if not, parameter is None.
parameter,owning_class = mcs.get_param_descriptor(attribute_name)
if parameter and not isinstance(value,Parameter):
if owning_class != mcs:
parameter = copy.copy(parameter)
parameter.owner = mcs
type.__setattr__(mcs,attribute_name,parameter)
mcs.__dict__[attribute_name].__set__(None,value)
else:
type.__setattr__(mcs,attribute_name,value)
if isinstance(value,Parameter):
mcs.__param_inheritance(attribute_name,value)
def __param_inheritance(mcs, param_name, param):
"""
Look for Parameter values in superclasses of this
Parameterized class.
Ordinarily, when a Python object is instantiated, attributes
not given values in the constructor will inherit the value
given in the object's class, or in its superclasses. For
Parameters owned by Parameterized classes, we have implemented
an additional level of default lookup, should this ordinary
lookup return only `Undefined`.
In such a case, i.e. when no non-`Undefined` value was found for a
Parameter by the usual inheritance mechanisms, we explicitly
look for Parameters with the same name in superclasses of this
Parameterized class, and use the first such value that we
find.
The goal is to be able to set the default value (or other
slots) of a Parameter within a Parameterized class, just as we
can set values for non-Parameter objects in Parameterized
classes, and have the values inherited through the
Parameterized hierarchy as usual.
Note that instantiate is handled differently: if there is a
parameter with the same name in one of the superclasses with
instantiate set to True, this parameter will inherit
instantiate=True.
"""
# get all relevant slots (i.e. slots defined in all
# superclasses of this parameter)
p_type = type(param)
slots = dict.fromkeys(p_type._all_slots_)
# note for some eventual future: python 3.6+ descriptors grew
# __set_name__, which could replace this and _set_names
setattr(param, 'owner', mcs)
del slots['owner']
# backwards compatibility (see Composite parameter)
if 'objtype' in slots:
setattr(param, 'objtype', mcs)
del slots['objtype']
supers = classlist(mcs)[::-1]
# Explicitly inherit instantiate from super class and
# check if type has changed to a more specific or different
# Parameter type, requiring extra validation
type_change = False
for superclass in supers:
super_param = superclass.__dict__.get(param_name)
if not isinstance(super_param, Parameter):
continue
if super_param.instantiate is True:
param.instantiate = True
super_type = type(super_param)
if not issubclass(super_type, p_type):
type_change = True
del slots['instantiate']
callables, slot_values = {}, {}
slot_overridden = False
for slot in slots.keys():
# Search up the hierarchy until param.slot (which has to
# be obtained using getattr(param,slot)) is not Undefined,
# is a new value (using identity) or we run out of classes
# to search.
for scls in supers:
# Class may not define parameter or slot might not be
# there because could be a more general type of Parameter
new_param = scls.__dict__.get(param_name)
if new_param is None or not hasattr(new_param, slot):
continue
new_value = getattr(new_param, slot)
old_value = slot_values.get(slot, Undefined)
if new_value is Undefined:
continue
elif new_value is old_value:
continue
elif old_value is Undefined:
slot_values[slot] = new_value
# If we already know we have to re-validate abort
# early to avoid costly lookups
if slot_overridden or type_change:
break
else:
if slot not in param._non_validated_slots:
slot_overridden = True
break
if slot_values.get(slot, Undefined) is Undefined:
try:
default_val = param._slot_defaults[slot]
except KeyError as e:
raise KeyError(
f'Slot {slot!r} of parameter {param_name!r} has no '
'default value defined in `_slot_defaults`'
) from e
if callable(default_val):
callables[slot] = default_val
else:
slot_values[slot] = default_val
elif slot == 'allow_refs':
# Track Parameters that explicitly declared no refs
explicit_no_refs = mcs._param__private.explicit_no_refs
if param.allow_refs is False:
explicit_no_refs.append(param.name)
elif param.allow_refs is True and param.name in explicit_no_refs:
explicit_no_refs.remove(param.name)
# Now set the actual slot values
for slot, value in slot_values.items():
setattr(param, slot, value)
# Avoid crosstalk between mutable slot values in different Parameter objects
if slot != "default":
v = getattr(param, slot)
if _is_mutable_container(v):
setattr(param, slot, copy.copy(v))
# Once all the static slots have been filled in, fill in the dynamic ones
# (which are only allowed to use static values or results are undefined)
for slot, fn in callables.items():
setattr(param, slot, fn(param))
# Once all the slot values have been set, call _update_state for Parameters
# that need updates to make sure they're set up correctly after inheritance.
param._update_state()
# If the type has changed to a more specific or different type
# or a slot value has been changed validate the default again.
# Hack: Had to disable re-validation of None values because the
# automatic appending of an unknown value on Selector opens a whole
# rabbit hole in regard to the validation.
if type_change or slot_overridden and param.default is not None:
try:
param._validate(param.default)
# Param has no base validation exception class. Param Parameters raise
# ValueError, TypeError, OSError exceptions but external Parameters
# might raise other types of error, so we catch them all.
except Exception as e:
msg = f'{_validate_error_prefix(param)} failed to validate its ' \
'default value on class creation, this is going to raise ' \
'an error in the future. '
parents = ', '.join(klass.__name__ for klass in mcs.__mro__[1:-2])
if not type_change and slot_overridden:
msg += (
f'The Parameter is defined with attributes which when '
'combined with attributes inherited from its parent '
f'classes ({parents}) make it invalid. '
'Please fix the Parameter attributes.'
)
elif type_change and not slot_overridden:
msg += (
f'The Parameter type changed between class {mcs.__name__!r} '
f'and one of its parent classes ({parents}) which '
f'made it invalid. Please fix the Parameter type.'
)
else:
# type_change and slot_overriden is not possible as when
# the type changes checking the slots is aborted for
# performance reasons.
pass
msg += f'\nValidation failed with:\n{e}'
warnings.warn(
msg,
category=_ParamFutureWarning,
stacklevel=4,
)
def get_param_descriptor(mcs,param_name):
"""
Goes up the class hierarchy (starting from the current class)
looking for a Parameter class attribute param_name. As soon as
one is found as a class attribute, that Parameter is returned
along with the class in which it is declared.
"""
classes = classlist(mcs)
for c in classes[::-1]:
attribute = c.__dict__.get(param_name)
if isinstance(attribute,Parameter):
return attribute,c
return None,None
# Whether script_repr should avoid reporting the values of parameters
# that are just inheriting their values from the class defaults.
# Because deepcopying creates a new object, cannot detect such
# inheritance when instantiate = True, so such values will be printed
# even if they are just being copied from the default.
script_repr_suppress_defaults=True
def script_repr(val, imports=None, prefix="\n ", settings=[],
qualify=True, unknown_value=None, separator="\n",
show_imports=True):
"""
Variant of pprint() designed for generating a (nearly) runnable script.
The output of script_repr(parameterized_obj) is meant to be a
string suitable for running using `python file.py`. Not every
object is guaranteed to have a runnable script_repr
representation, but it is meant to be a good starting point for
generating a Python script that (after minor edits) can be
evaluated to get a newly initialized object similar to the one
provided.
The new object will only have the same parameter state, not the
same internal (attribute) state; the script_repr captures only
the state of the Parameters of that object and not any other
attributes it may have.
If show_imports is True (default), includes import statements
for each of the modules required for the objects being
instantiated. This list may not be complete, as it typically
includes only the imports needed for the Parameterized object
itself, not for values that may have been supplied to Parameters.
Apart from show_imports, accepts the same arguments as pprint(),
so see pprint() for explanations of the arguments accepted. The
default values of each of these arguments differ from pprint() in
ways that are more suitable for saving as a separate script than
for e.g. pretty-printing at the Python prompt.
"""
if imports is None:
imports = []
rep = pprint(val, imports, prefix, settings, unknown_value,
qualify, separator)
imports = list(set(imports))
imports_str = ("\n".join(imports) + "\n\n") if show_imports else ""
return imports_str + rep
# PARAM2_DEPRECATION: Remove entirely unused settings argument
def pprint(val,imports=None, prefix="\n ", settings=[],
unknown_value='', qualify=False, separator=''):
"""
Pretty printed representation of a parameterized
object that may be evaluated with eval.
Similar to repr except introspection of the constructor (__init__)
ensures a valid and succinct representation is generated.
Only parameters are represented (whether specified as standard,
positional, or keyword arguments). Parameters specified as
positional arguments are always shown, followed by modified
parameters specified as keyword arguments, sorted by precedence.
unknown_value determines what to do where a representation cannot be
generated for something required to recreate the object. Such things
include non-parameter positional and keyword arguments, and certain
values of parameters (e.g. some random state objects).
Supplying an unknown_value of None causes unrepresentable things
to be silently ignored. If unknown_value is a string, that
string will appear in place of any unrepresentable things. If
unknown_value is False, an Exception will be raised if an
unrepresentable value is encountered.
If supplied, imports should be a list, and it will be populated
with the set of imports required for the object and all of its
parameter values.
If qualify is True, the class's path will be included (e.g. "a.b.C()"),
otherwise only the class will appear ("C()").
Parameters will be separated by a comma only by default, but the
separator parameter allows an additional separator to be supplied
(e.g. a newline could be supplied to have each Parameter appear on a
separate line).
Instances of types that require special handling can use the
script_repr_reg dictionary. Using the type as a key, add a
function that returns a suitable representation of instances of
that type, and adds the required import statement. The repr of a
parameter can be suppressed by returning None from the appropriate
hook in script_repr_reg.
"""
if imports is None:
imports = []
if isinstance(val,type):
rep = type_script_repr(val,imports,prefix,settings)
elif type(val) in script_repr_reg:
rep = script_repr_reg[type(val)](val,imports,prefix,settings)
elif isinstance(val, Parameterized) or (type(val) is type and issubclass(val, Parameterized)):
rep=val.param.pprint(imports=imports, prefix=prefix+" ",
qualify=qualify, unknown_value=unknown_value,
separator=separator)
else:
rep=repr(val)
return rep
# Registry for special handling for certain types in script_repr and pprint
script_repr_reg = {}
# currently only handles list and tuple
def container_script_repr(container,imports,prefix,settings):
result=[]
for i in container:
result.append(pprint(i,imports,prefix,settings))
## (hack to get container brackets)
if isinstance(container,list):
d1,d2='[',']'
elif isinstance(container,tuple):
d1,d2='(',')'
else:
raise NotImplementedError
rep=d1+','.join(result)+d2
# no imports to add for built-in types
return rep
def empty_script_repr(*args): # pyflakes:ignore (unused arguments):
return None
try:
# Suppress scriptrepr for objects not yet having a useful string representation
import numpy
script_repr_reg[random.Random] = empty_script_repr
script_repr_reg[numpy.random.RandomState] = empty_script_repr
except ImportError:
pass # Support added only if those libraries are available
def function_script_repr(fn,imports,prefix,settings):
name = fn.__name__
module = fn.__module__
imports.append('import %s'%module)
return module+'.'+name
def type_script_repr(type_,imports,prefix,settings):
module = type_.__module__
if module!='__builtin__':
imports.append('import %s'%module)
return module+'.'+type_.__name__
script_repr_reg[list] = container_script_repr
script_repr_reg[tuple] = container_script_repr
script_repr_reg[FunctionType] = function_script_repr
#: If not None, the value of this Parameter will be called (using '()')
#: before every call to __db_print, and is expected to evaluate to a
#: string that is suitable for prefixing messages and warnings (such
#: as some indicator of the global state).
dbprint_prefix=None
def truncate(str_, maxlen = 30):
"""Return HTML-safe truncated version of given string"""
rep = (str_[:(maxlen-2)] + '..') if (len(str_) > (maxlen-2)) else str_
return html.escape(rep)
def _get_param_repr(key, val, p, vallen=30, doclen=40):
"""HTML representation for a single Parameter object and its value"""
if isinstance(val, Parameterized) or (type(val) is type and issubclass(val, Parameterized)):
value = val.param._repr_html_(open=False)
elif hasattr(val, "_repr_html_"):
value = val._repr_html_()
else:
value = truncate(repr(val), vallen)
if hasattr(p, 'bounds'):
if p.bounds is None:
range_ = ''
elif hasattr(p,'inclusive_bounds'):
# Numeric bounds use ( and [ to indicate exclusive and inclusive
bl,bu = p.bounds
il,iu = p.inclusive_bounds
lb = '' if bl is None else ('>=' if il else '>') + str(bl)
ub = '' if bu is None else ('<=' if iu else '<') + str(bu)
range_ = lb + (', ' if lb and bu else '') + ub
else:
range_ = repr(p.bounds)
elif hasattr(p, 'objects') and p.objects:
range_ = ', '.join(list(map(repr, p.objects)))
elif hasattr(p, 'class_'):
if isinstance(p.class_, tuple):
range_ = ' | '.join(kls.__name__ for kls in p.class_)
else:
range_ = p.class_.__name__
elif hasattr(p, 'regex') and p.regex is not None:
range_ = f'regex({p.regex})'
else:
range_ = ''
if p.readonly:
range_ = ' '.join(s for s in ['read-only', range_] if s)
elif p.constant:
range_ = ' '.join(s for s in ['constant', range_] if s)
if getattr(p, 'allow_None', False):
range_ = ' '.join(s for s in ['nullable', range_] if s)
tooltip = f' class="param-doc-tooltip" data-tooltip="{escape(p.doc.strip())}"' if p.doc else ''
return (
f'
'
f'
{key}
'
f'
{value}
'
f'
{p.__class__.__name__}
'
f'
{range_}
'
f'
\n'
)
def _parameterized_repr_html(p, open):
"""HTML representation for a Parameterized object"""
if isinstance(p, Parameterized):
cls = p.__class__
title = cls.name + "()"
value_field = 'Value'
else:
cls = p
title = cls.name
value_field = 'Default'
tooltip_css = """
.param-doc-tooltip{
position: relative;
cursor: help;
}
.param-doc-tooltip:hover:after{
content: attr(data-tooltip);
background-color: black;
color: #fff;
border-radius: 3px;
padding: 10px;
position: absolute;
z-index: 1;
top: -5px;
left: 100%;
margin-left: 10px;
min-width: 250px;
}
.param-doc-tooltip:hover:before {
content: "";
position: absolute;
top: 50%;
left: 100%;
margin-top: -5px;
border-width: 5px;
border-style: solid;
border-color: transparent black transparent transparent;
}
"""
openstr = " open" if open else ""
param_values = p.param.values().items()
contents = "".join(_get_param_repr(key, val, p.param[key])
for key, val in param_values)
return (
f'\n'
f'\n'
' \n'
f' {title}\n'
' \n'
'
\n'
'
\n'
f'
Name
{value_field}
Type
Range
\n'
f'{contents}\n'
'
\n
\n\n'
)
# _ClassPrivate and _InstancePrivate are the private namespaces of Parameterized
# classes and instance respectively, stored on the `_param__private` attribute.
# They are implemented with slots for performance reasons.
class _ClassPrivate:
"""
parameters_state: dict
Dict holding some transient states
disable_instance_params: bool
Whether to disable instance parameters
renamed: bool
Whethe the class has been renamed by a super class
params: dict
Dict of parameter_name:parameter
"""
__slots__ = [
'parameters_state',
'disable_instance_params',
'renamed',
'params',
'initialized',
'signature',
'explicit_no_refs',
]
def __init__(
self,
parameters_state=None,
disable_instance_params=False,
explicit_no_refs=None,
renamed=False,
params=None,
):
if parameters_state is None:
parameters_state = {
"BATCH_WATCH": False, # If true, Event and watcher objects are queued.
"TRIGGER": False,
"events": [], # Queue of batched events
"watchers": [] # Queue of batched watchers
}
self.parameters_state = parameters_state
self.disable_instance_params = disable_instance_params
self.renamed = renamed
self.params = {} if params is None else params
self.initialized = False
self.signature = None
self.explicit_no_refs = [] if explicit_no_refs is None else explicit_no_refs
def __getstate__(self):
return {slot: getattr(self, slot) for slot in self.__slots__}
def __setstate__(self, state):
for k, v in state.items():
setattr(self, k, v)
class _InstancePrivate:
"""
initialized: bool
Flag that can be tested to see if e.g. constant Parameters can still be set
parameters_state: dict
Dict holding some transient states
dynamic_watchers: defaultdict
Dynamic watchers
ref_watchers: list[Watcher]
Watchers used for internal references
params: dict
Dict of parameter_name:parameter
refs: dict
Dict of parameter name:reference
watchers: dict
Dict of dict:
parameter_name:
parameter_attribute (e.g. 'value'): list of `Watcher`s
values: dict
Dict of parameter name: value
"""
__slots__ = [
'initialized',
'parameters_state',
'dynamic_watchers',
'params',
'async_refs',
'refs',
'ref_watchers',
'syncing',
'watchers',
'values',
'explicit_no_refs',
]
def __init__(
self,
initialized=False,
parameters_state=None,
dynamic_watchers=None,
refs=None,
params=None,
watchers=None,
values=None,
explicit_no_refs=None
):
self.initialized = initialized
self.explicit_no_refs = [] if explicit_no_refs is None else explicit_no_refs
self.syncing = set()
if parameters_state is None:
parameters_state = {
"BATCH_WATCH": False, # If true, Event and watcher objects are queued.
"TRIGGER": False,
"events": [], # Queue of batched events
"watchers": [] # Queue of batched watchers
}
self.ref_watchers = []
self.async_refs = {}
self.parameters_state = parameters_state
self.dynamic_watchers = defaultdict(list) if dynamic_watchers is None else dynamic_watchers
self.params = {} if params is None else params
self.refs = {} if refs is None else refs
self.watchers = {} if watchers is None else watchers
self.values = {} if values is None else values
def __getstate__(self):
return {slot: getattr(self, slot) for slot in self.__slots__}
def __setstate__(self, state):
for k, v in state.items():
setattr(self, k, v)
class Parameterized(metaclass=ParameterizedMetaclass):
"""
Base class for named objects that support Parameters and message
formatting.
Automatic object naming: Every Parameterized instance has a name
parameter. If the user doesn't designate a name= argument
when constructing the object, the object will be given a name
consisting of its class name followed by a unique 5-digit number.
Automatic parameter setting: The Parameterized __init__ method
will automatically read the list of keyword parameters. If any
keyword matches the name of a Parameter (see Parameter class)
defined in the object's class or any of its superclasses, that
parameter in the instance will get the value given as a keyword
argument. For example:
class Foo(Parameterized):
xx = Parameter(default=1)
foo = Foo(xx=20)
in this case foo.xx gets the value 20.
When initializing a Parameterized instance ('foo' in the example
above), the values of parameters can be supplied as keyword
arguments to the constructor (using parametername=parametervalue);
these values will override the class default values for this one
instance.
If no 'name' parameter is supplied, self.name defaults to the
object's class name with a unique number appended to it.
Message formatting: Each Parameterized instance has several
methods for optionally printing output. This functionality is
based on the standard Python 'logging' module; using the methods
provided here, wraps calls to the 'logging' module's root logger
and prepends each message with information about the instance
from which the call was made. For more information on how to set
the global logging level and change the default message prefix,
see documentation for the 'logging' module.
"""
name = String(default=None, constant=True, doc="""
String identifier for this object.""")
def __init__(self, **params):
global object_count
# Setting a Parameter value in an __init__ block before calling
# Parameterized.__init__ (via super() generally) already sets the
# _InstancePrivate namespace over the _ClassPrivate namespace
# (see Parameter.__set__) so we shouldn't override it here.
if not isinstance(self._param__private, _InstancePrivate):
self._param__private = _InstancePrivate(
explicit_no_refs=type(self)._param__private.explicit_no_refs
)
# Skip generating a custom instance name when a class in the hierarchy
# has overriden the default of the `name` Parameter.
if self.param.name.default == self.__class__.__name__:
self.param._generate_name()
refs, deps = self.param._setup_params(**params)
object_count += 1
self._param__private.initialized = True
self.param._setup_refs(deps)
self.param._update_deps(init=True)
self._param__private.refs = refs
@property
def param(self):
return Parameters(self.__class__, self=self)
#PARAM3_DEPRECATION
@property
@_deprecated(extra_msg="Use `inst.param.watchers` instead.", warning_cat=_ParamFutureWarning)
def _param_watchers(self):
return self._param__private.watchers
#PARAM3_DEPRECATION
@_param_watchers.setter
@_deprecated(extra_msg="Use `inst.param.watchers = ...` instead.", warning_cat=_ParamFutureWarning)
def _param_watchers(self, value):
self._param__private.watchers = value
# 'Special' methods
def __getstate__(self):
"""
Save the object's state: return a dictionary that is a shallow
copy of the object's __dict__ and that also includes the
object's __slots__ (if it has any).
"""
# Unclear why this is a copy and not simply state.update(self.__dict__)
state = self.__dict__.copy()
for slot in get_occupied_slots(self):
state[slot] = getattr(self,slot)
# Note that Parameterized object pickling assumes that
# attributes to be saved are only in __dict__ or __slots__
# (the standard Python places to store attributes, so that's a
# reasonable assumption). (Additionally, class attributes that
# are Parameters are also handled, even when they haven't been
# instantiated - see PickleableClassAttributes.)
return state
def __setstate__(self, state):
"""
Restore objects from the state dictionary to this object.
During this process the object is considered uninitialized.
"""
explicit_no_refs = type(self)._param__private.explicit_no_refs
self._param__private = _InstancePrivate(explicit_no_refs=explicit_no_refs)
self._param__private.initialized = False
_param__private = state.get('_param__private', None)
if _param__private is None:
_param__private = _InstancePrivate(explicit_no_refs=explicit_no_refs)
# When making a copy the internal watchers have to be
# recreated and point to the new instance
if _param__private.watchers:
param_watchers = _param__private.watchers
for p, attrs in param_watchers.items():
for attr, watchers in attrs.items():
new_watchers = []
for watcher in watchers:
watcher_args = list(watcher)
if watcher.inst is not None:
watcher_args[0] = self
fn = watcher.fn
if hasattr(fn, '_watcher_name'):
watcher_args[2] = _m_caller(self, fn._watcher_name)
elif get_method_owner(fn) is watcher.inst:
watcher_args[2] = getattr(self, fn.__name__)
new_watchers.append(Watcher(*watcher_args))
param_watchers[p][attr] = new_watchers
state.pop('param', None)
for name,value in state.items():
setattr(self,name,value)
self._param__private.initialized = True
@_recursive_repr()
def __repr__(self):
"""
Provide a nearly valid Python representation that could be used to recreate
the item with its parameters, if executed in the appropriate environment.
Returns 'classname(parameter1=x,parameter2=y,...)', listing
all the parameters of this object.
"""
try:
settings = [f'{name}={val!r}'
for name, val in self.param.values().items()]
except RuntimeError: # Handle recursion in parameter depth
settings = []
return self.__class__.__name__ + "(" + ", ".join(settings) + ")"
def __str__(self):
"""Return a short representation of the name and class of this object."""
return f"<{self.__class__.__name__} {self.name}>"
def print_all_param_defaults():
"""Print the default values for all imported Parameters."""
print("_______________________________________________________________________________")
print("")
print(" Parameter Default Values")
print("")
classes = descendents(Parameterized)
classes.sort(key=lambda x:x.__name__)
for c in classes:
c.print_param_defaults()
print("_______________________________________________________________________________")
# As of Python 2.6+, a fn's **args no longer has to be a
# dictionary. This might allow us to use a decorator to simplify using
# ParamOverrides (if that does indeed make them simpler to use).
# http://docs.python.org/whatsnew/2.6.html
class ParamOverrides(dict):
"""
A dictionary that returns the attribute of a specified object if
that attribute is not present in itself.
Used to override the parameters of an object.
"""
# NOTE: Attribute names of this object block parameters of the
# same name, so all attributes of this object should have names
# starting with an underscore (_).
def __init__(self,overridden,dict_,allow_extra_keywords=False):
"""
If allow_extra_keywords is False, then all keys in the
supplied dict_ must match parameter names on the overridden
object (otherwise a warning will be printed).
If allow_extra_keywords is True, then any items in the
supplied dict_ that are not also parameters of the overridden
object will be available via the extra_keywords() method.
"""
# This method should be fast because it's going to be
# called a lot. This _might_ be faster (not tested):
# def __init__(self,overridden,**kw):
# ...
# dict.__init__(self,**kw)
self._overridden = overridden
dict.__init__(self,dict_)
if allow_extra_keywords:
self._extra_keywords=self._extract_extra_keywords(dict_)
else:
self._check_params(dict_)
def extra_keywords(self):
"""
Return a dictionary containing items from the originally
supplied `dict_` whose names are not parameters of the
overridden object.
"""
return self._extra_keywords
def param_keywords(self):
"""
Return a dictionary containing items from the originally
supplied `dict_` whose names are parameters of the
overridden object (i.e. not extra keywords/parameters).
"""
return {key: self[key] for key in self if key not in self.extra_keywords()}
def __missing__(self,name):
# Return 'name' from the overridden object
return getattr(self._overridden,name)
def __repr__(self):
# As dict.__repr__, but indicate the overridden object
return dict.__repr__(self)+" overriding params from %s"%repr(self._overridden)
def __getattr__(self,name):
# Provide 'dot' access to entries in the dictionary.
# (This __getattr__ method is called only if 'name' isn't an
# attribute of self.)
return self.__getitem__(name)
def __setattr__(self,name,val):
# Attributes whose name starts with _ are set on self (as
# normal), but all other attributes are inserted into the
# dictionary.
if not name.startswith('_'):
self.__setitem__(name,val)
else:
dict.__setattr__(self,name,val)
def get(self, key, default=None):
try:
return self[key]
except KeyError:
return default
def __contains__(self, key):
return key in self.__dict__ or key in self._overridden.param
def _check_params(self,params):
"""
Print a warning if params contains something that is not a
Parameter of the overridden object.
"""
overridden_object_params = list(self._overridden.param)
for item in params:
if item not in overridden_object_params:
self.param.warning("'%s' will be ignored (not a Parameter).",item)
def _extract_extra_keywords(self,params):
"""
Return any items in params that are not also
parameters of the overridden object.
"""
extra_keywords = {}
overridden_object_params = list(self._overridden.param)
for name, val in params.items():
if name not in overridden_object_params:
extra_keywords[name]=val
# Could remove name from params (i.e. del params[name])
# so that it's only available via extra_keywords()
return extra_keywords
# Helper function required by ParameterizedFunction.__reduce__
def _new_parameterized(cls):
return Parameterized.__new__(cls)
class ParameterizedFunction(Parameterized):
"""
Acts like a Python function, but with arguments that are Parameters.
Implemented as a subclass of Parameterized that, when instantiated,
automatically invokes __call__ and returns the result, instead of
returning an instance of the class.
To obtain an instance of this class, call instance().
"""
__abstract = True
def __str__(self):
return self.__class__.__name__+"()"
@bothmethod
def instance(self_or_cls,**params):
"""
Return an instance of this class, copying parameters from any
existing instance provided.
"""
if isinstance (self_or_cls,ParameterizedMetaclass):
cls = self_or_cls
else:
p = params
params = self_or_cls.param.values()
params.update(p)
params.pop('name')
cls = self_or_cls.__class__
inst=Parameterized.__new__(cls)
Parameterized.__init__(inst,**params)
if 'name' in params: inst.__name__ = params['name']
else: inst.__name__ = self_or_cls.name
return inst
def __new__(class_,*args,**params):
# Create and __call__() an instance of this class.
inst = class_.instance()
inst.param._set_name(class_.__name__)
return inst.__call__(*args,**params)
def __call__(self,*args,**kw):
raise NotImplementedError("Subclasses must implement __call__.")
def __reduce__(self):
# Control reconstruction (during unpickling and copying):
# ensure that ParameterizedFunction.__new__ is skipped
state = ParameterizedFunction.__getstate__(self)
# Here it's necessary to use a function defined at the
# module level rather than Parameterized.__new__ directly
# because otherwise pickle will find .__new__'s module to be
# __main__. Pretty obscure aspect of pickle.py...
return (_new_parameterized,(self.__class__,),state)
def _pprint(self, imports=None, prefix="\n ",unknown_value='',
qualify=False, separator=""):
"""
Same as self.param.pprint, except that X.classname(Y
is replaced with X.classname.instance(Y
"""
r = self.param.pprint(imports,prefix,
unknown_value=unknown_value,
qualify=qualify,separator=separator)
classname=self.__class__.__name__
return r.replace(".%s("%classname,".%s.instance("%classname)
class default_label_formatter(ParameterizedFunction):
"Default formatter to turn parameter names into appropriate widget labels."
capitalize = Parameter(default=True, doc="""
Whether or not the label should be capitalized.""")
replace_underscores = Parameter(default=True, doc="""
Whether or not underscores should be replaced with spaces.""")
overrides = Parameter(default={}, doc="""
Allows custom labels to be specified for specific parameter
names using a dictionary where key is the parameter name and the
value is the desired label.""")
def __call__(self, pname):
if pname in self.overrides:
return self.overrides[pname]
if self.replace_underscores:
pname = pname.replace('_',' ')
if self.capitalize:
pname = pname[:1].upper() + pname[1:]
return pname
label_formatter = default_label_formatter
# PARAM3_DEPRECATION: Should be able to remove this; was originally
# adapted from OProperty from
# infinitesque.net/articles/2005/enhancing%20Python's%20property.xhtml
# but since python 2.6 the getter, setter, and deleter attributes of
# a property should provide similar functionality already.
class overridable_property:
"""
The same as Python's "property" attribute, but allows the accessor
methods to be overridden in subclasses.
.. deprecated:: 2.0.0
"""
# Delays looking up the accessors until they're needed, rather
# than finding them when the class is first created.
# Based on the emulation of PyProperty_Type() in Objects/descrobject.c
def __init__(self, fget=None, fset=None, fdel=None, doc=None):
warnings.warn(
message="overridable_property has been deprecated.",
category=_ParamDeprecationWarning,
stacklevel=2,
)
self.fget = fget
self.fset = fset
self.fdel = fdel
self.__doc__ = doc
def __get__(self, obj, objtype=None):
if obj is None:
return self
if self.fget is None:
raise AttributeError("unreadable attribute")
if self.fget.__name__ == '' or not self.fget.__name__:
return self.fget(obj)
else:
return getattr(obj, self.fget.__name__)()
def __set__(self, obj, value):
if self.fset is None:
raise AttributeError("can't set attribute")
if self.fset.__name__ == '' or not self.fset.__name__:
self.fset(obj, value)
else:
getattr(obj, self.fset.__name__)(value)
def __delete__(self, obj):
if self.fdel is None:
raise AttributeError("can't delete attribute")
if self.fdel.__name__ == '' or not self.fdel.__name__:
self.fdel(obj)
else:
getattr(obj, self.fdel.__name__)()
param-2.1.1/param/parameters.py 0000664 0000000 0000000 00000316604 14636363363 0016457 0 ustar 00root root 0000000 0000000 """
Parameters are a kind of class attribute allowing special behavior,
including dynamically generated parameter values, documentation
strings, constant and read-only parameters, and type or range checking
at assignment time.
Potentially useful for any large Python program that needs
user-modifiable object attributes; see the Parameter and Parameterized
classes for more information. If you do not want to add a dependency
on external code by importing from a separately installed param
package, you can simply save this file as param.py and copy it and
parameterized.py directly into your own package.
This file contains subclasses of Parameter, implementing specific
parameter types (e.g. Number), and also imports the definition of
Parameters and Parameterized classes.
"""
import collections
import copy
import datetime as dt
import glob
import inspect
import numbers
import os.path
import pathlib
import re
import sys
import typing
import warnings
from collections import OrderedDict
from contextlib import contextmanager
from .parameterized import (
Parameterized, Parameter, ParameterizedFunction, ParamOverrides, String,
Undefined, get_logger, instance_descriptor, dt_types,
_int_types, _identity_hook
)
from ._utils import (
ParamDeprecationWarning as _ParamDeprecationWarning,
_deprecate_positional_args,
_deprecated,
_dict_update,
_validate_error_prefix,
_deserialize_from_path,
_named_objs,
_produce_value,
_get_min_max_value,
_is_number,
concrete_descendents,
_abbreviate_paths,
_to_datetime,
)
#-----------------------------------------------------------------------------
# Utilities
#-----------------------------------------------------------------------------
def param_union(*parameterizeds, warn=True):
"""
Given a set of Parameterized objects, returns a dictionary
with the union of all param name,value pairs across them.
Parameters
----------
warn : bool, optional
Wether to warn if the same parameter have been given multiple values,
otherwise use the last value, by default True
Returns
-------
dict
Union of all param name,value pairs
"""
d = {}
for o in parameterizeds:
for k in o.param:
if k != 'name':
if k in d and warn:
get_logger().warning(f"overwriting parameter {k}")
d[k] = getattr(o, k)
return d
def guess_param_types(**kwargs):
"""
Given a set of keyword literals, promote to the appropriate
parameter type based on some simple heuristics.
"""
params = {}
for k, v in kwargs.items():
kws = dict(default=v, constant=True)
if isinstance(v, Parameter):
params[k] = v
elif isinstance(v, dt_types):
params[k] = Date(**kws)
elif isinstance(v, bool):
params[k] = Boolean(**kws)
elif isinstance(v, int):
params[k] = Integer(**kws)
elif isinstance(v, float):
params[k] = Number(**kws)
elif isinstance(v, str):
params[k] = String(**kws)
elif isinstance(v, dict):
params[k] = Dict(**kws)
elif isinstance(v, tuple):
if all(_is_number(el) for el in v):
params[k] = NumericTuple(**kws)
elif all(isinstance(el, dt_types) for el in v) and len(v)==2:
params[k] = DateRange(**kws)
else:
params[k] = Tuple(**kws)
elif isinstance(v, list):
params[k] = List(**kws)
else:
if 'numpy' in sys.modules:
from numpy import ndarray
if isinstance(v, ndarray):
params[k] = Array(**kws)
continue
if 'pandas' in sys.modules:
from pandas import (
DataFrame as pdDFrame, Series as pdSeries
)
if isinstance(v, pdDFrame):
params[k] = DataFrame(**kws)
continue
elif isinstance(v, pdSeries):
params[k] = Series(**kws)
continue
params[k] = Parameter(**kws)
return params
def parameterized_class(name, params, bases=Parameterized):
"""
Dynamically create a parameterized class with the given name and the
supplied parameters, inheriting from the specified base(s).
"""
if not (isinstance(bases, list) or isinstance(bases, tuple)):
bases=[bases]
return type(name, tuple(bases), params)
def guess_bounds(params, **overrides):
"""
Given a dictionary of Parameter instances, return a corresponding
set of copies with the bounds appropriately set.
If given a set of override keywords, use those numeric tuple bounds.
"""
guessed = {}
for name, p in params.items():
new_param = copy.copy(p)
if isinstance(p, (Integer, Number)):
if name in overrides:
minv,maxv = overrides[name]
else:
minv, maxv, _ = _get_min_max_value(None, None, value=p.default)
new_param.bounds = (minv, maxv)
guessed[name] = new_param
return guessed
def get_soft_bounds(bounds, softbounds):
"""
For each soft bound (upper and lower), if there is a defined bound
(not equal to None) and does not exceed the hard bound, then it is
returned. Otherwise it defaults to the hard bound. The hard bound
could still be None.
"""
if bounds is None:
hl, hu = (None, None)
else:
hl, hu = bounds
if softbounds is None:
sl, su = (None, None)
else:
sl, su = softbounds
if sl is None or (hl is not None and slhu):
u = hu
else:
u = su
return (l, u)
class Infinity:
"""
An instance of this class represents an infinite value. Unlike
Python's float('inf') value, this object can be safely compared
with gmpy numeric types across different gmpy versions.
All operators on Infinity() return Infinity(), apart from the
comparison and equality operators. Equality works by checking
whether the two objects are both instances of this class.
"""
def __eq__ (self,other): return isinstance(other,self.__class__)
def __ne__ (self,other): return not self==other
def __lt__ (self,other): return False
def __le__ (self,other): return False
def __gt__ (self,other): return True
def __ge__ (self,other): return True
def __add__ (self,other): return self
def __radd__(self,other): return self
def __ladd__(self,other): return self
def __sub__ (self,other): return self
def __iadd__ (self,other): return self
def __isub__(self,other): return self
def __repr__(self): return "Infinity()"
def __str__ (self): return repr(self)
class Time(Parameterized):
"""
A callable object returning a number for the current time.
Here 'time' is an abstract concept that can be interpreted in any
useful way. For instance, in a simulation, it would be the
current simulation time, while in a turn-taking game it could be
the number of moves so far. The key intended usage is to allow
independent Parameterized objects with Dynamic parameters to
remain consistent with a global reference.
The time datatype (time_type) is configurable, but should
typically be an exact numeric type like an integer or a rational,
so that small floating-point errors do not accumulate as time is
incremented repeatedly.
When used as a context manager using the 'with' statement
(implemented by the __enter__ and __exit__ special methods), entry
into a context pushes the state of the Time object, allowing the
effect of changes to the time value to be explored by setting,
incrementing or decrementing time as desired. This allows the
state of time-dependent objects to be modified temporarily as a
function of time, within the context's block. For instance, you
could use the context manager to "see into the future" to collect
data over multiple times, without affecting the global time state
once exiting the context. Of course, you need to be careful not to
do anything while in context that would affect the lasting state
of your other objects, if you want things to return to their
starting state when exiting the context.
The starting time value of a new Time object is 0, converted to
the chosen time type. Here is an illustration of how time can be
manipulated using a Time object:
>>> time = Time(until=20, timestep=1)
>>> 'The initial time is %s' % time()
'The initial time is 0'
>>> 'Setting the time to %s' % time(5)
'Setting the time to 5'
>>> time += 5
>>> 'After incrementing by 5, the time is %s' % time()
'After incrementing by 5, the time is 10'
>>> with time as t: # Entering a context
... 'Time before iteration: %s' % t()
... 'Iteration: %s' % [val for val in t]
... 'Time after iteration: %s' % t()
... t += 2
... 'The until parameter may be exceeded outside iteration: %s' % t()
'Time before iteration: 10'
'Iteration: [10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20]'
'Time after iteration: 20'
'The until parameter may be exceeded outside iteration: 22'
>>> 'After exiting the context the time is back to %s' % time()
'After exiting the context the time is back to 10'
"""
_infinitely_iterable = True
forever = Infinity()
label= String(default='Time', doc="""
The label given to the Time object. Can be used to convey
more specific notions of time as appropriate. For instance,
the label could be 'Simulation Time' or 'Duration'.""")
time_type = Parameter(default=int, constant=True, doc="""
Callable that Time will use to convert user-specified time
values into the current time; all times will be of the resulting
numeric type.
By default, time is of integer type, but you can supply any
arbitrary-precision type like a fixed-point decimal or a
rational, to allow fractional times. Floating-point times are
also allowed, but are not recommended because they will suffer
from accumulated rounding errors. For instance, incrementing
a floating-point value 0.0 by 0.05, 20 times, will not reach
1.0 exactly. Instead, it will be slightly higher than 1.0,
because 0.05 cannot be represented exactly in a standard
floating point numeric type. Fixed-point or rational types
should be able to handle such computations exactly, avoiding
accumulation issues over long time intervals.
Some potentially useful exact number classes:
- int: Suitable if all times can be expressed as integers.
- Python's decimal.Decimal and fractions.Fraction classes:
widely available but slow and also awkward to specify times
(e.g. cannot simply type 0.05, but have to use a special
constructor or a string).
- fixedpoint.FixedPoint: Allows a natural representation of
times in decimal notation, but very slow and needs to be
installed separately.
- gmpy.mpq: Allows a natural representation of times in
decimal notation, and very fast because it uses the GNU
Multi-Precision library, but needs to be installed
separately and depends on a non-Python library. gmpy.mpq
is gmpy's rational type.
""")
timestep = Parameter(default=1.0,doc="""
Stepsize to be used with the iterator interface.
Time can be advanced or decremented by any value, not just
those corresponding to the stepsize, and so this value is only
a default.""")
until = Parameter(default=forever,doc="""
Declaration of an expected end to time values, if any. When
using the iterator interface, iteration will end before this
value is exceeded.""")
unit = String(default=None, doc="""
The units of the time dimensions. The default of None is set
as the global time function may on an arbitrary time base.
Typical values for the parameter are 'seconds' (the SI unit
for time) or subdivisions thereof (e.g. 'milliseconds').""")
def __init__(self, **params):
super().__init__(**params)
self._time = self.time_type(0)
self._exhausted = None
self._pushed_state = []
def __eq__(self, other):
if not isinstance(other, Time):
return False
self_params = (self.timestep,self.until)
other_params = (other.timestep,other.until)
if self_params != other_params:
return False
return True
def __ne__(self, other):
return not (self == other)
def __iter__(self): return self
def __next__(self):
timestep = self.time_type(self.timestep)
if self._exhausted is None:
self._exhausted = False
elif (self._time + timestep) <= self.until:
self._time += timestep
else:
self._exhausted = None
raise StopIteration
return self._time
def __call__(self, val=None, time_type=None):
"""
When called with no arguments, returns the current time value.
When called with a specified val, sets the time to it.
When called with a specified time_type, changes the time_type
and sets the current time to the given val (which *must* be
specified) converted to that time type. To ensure that
the current state remains consistent, this is normally the only
way to change the time_type of an existing Time instance.
"""
if time_type and val is None:
raise Exception("Please specify a value for the new time_type.")
if time_type:
type_param = self.param.objects('existing').get('time_type')
type_param.constant = False
self.time_type = time_type
type_param.constant = True
if val is not None:
self._time = self.time_type(val)
return self._time
def advance(self, val):
self += val
def __iadd__(self, other):
self._time = self._time + self.time_type(other)
return self
def __isub__(self, other):
self._time = self._time - self.time_type(other)
return self
def __enter__(self):
"""Enter the context and push the current state."""
self._pushed_state.append((self._time, self.timestep, self.until))
self.in_context = True
return self
def __exit__(self, exc, *args):
"""
Exit from the current context, restoring the previous state.
The StopIteration exception raised in context will force the
context to exit. Any other exception exc that is raised in the
block will not be caught.
"""
(self._time, self.timestep, self.until) = self._pushed_state.pop()
self.in_context = len(self._pushed_state) != 0
if exc is StopIteration:
return True
#-----------------------------------------------------------------------------
# Parameters
#-----------------------------------------------------------------------------
#-----------------------------------------------------------------------------
# Dynamic/Number
#-----------------------------------------------------------------------------
class Dynamic(Parameter):
"""
Parameter whose value can be generated dynamically by a callable
object.
If a Parameter is declared as Dynamic, it can be set a callable
object (such as a function or callable class), and getting the
parameter's value will call that callable.
Note that at present, the callable object must allow attributes
to be set on itself.
If set as time_dependent, setting the Dynamic.time_fn allows the
production of dynamic values to be controlled: a new value will be
produced only if the current value of time_fn is different from
what it was the last time the parameter value was requested.
By default, the Dynamic parameters are not time_dependent so that
new values are generated on every call regardless of the time. The
default time_fn used when time_dependent is a single Time instance
that allows general manipulations of time. It may be set to some
other callable as required so long as a number is returned on each
call.
"""
time_fn = Time()
time_dependent = False
@typing.overload
def __init__(
self, default=None, *,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, **params):
"""
Call the superclass's __init__ and set instantiate=True if the
default is dynamic.
"""
super().__init__(default=default, **params)
if callable(self.default):
self._set_instantiate(True)
self._initialize_generator(self.default)
def _initialize_generator(self,gen,obj=None):
"""
Add 'last time' and 'last value' attributes to the generator.
"""
# Could use a dictionary to hold these things.
if hasattr(obj,"_Dynamic_time_fn"):
gen._Dynamic_time_fn = obj._Dynamic_time_fn
gen._Dynamic_last = None
# Would have usede None for this, but can't compare a fixedpoint
# number with None (e.g. 1>None but FixedPoint(1)>None can't be done)
gen._Dynamic_time = -1
gen._saved_Dynamic_last = []
gen._saved_Dynamic_time = []
def __get__(self,obj,objtype):
"""
Call the superclass's __get__; if the result is not dynamic
return that result, otherwise ask that result to produce a
value and return it.
"""
gen = super().__get__(obj,objtype)
if not hasattr(gen,'_Dynamic_last'):
return gen
else:
return self._produce_value(gen)
@instance_descriptor
def __set__(self,obj,val):
"""
Call the superclass's set and keep this parameter's
instantiate value up to date (dynamic parameters
must be instantiated).
If val is dynamic, initialize it as a generator.
"""
super().__set__(obj,val)
dynamic = callable(val)
if dynamic: self._initialize_generator(val,obj)
if obj is None: self._set_instantiate(dynamic)
def _produce_value(self,gen,force=False):
"""
Return a value from gen.
If there is no time_fn, then a new value will be returned
(i.e. gen will be asked to produce a new value).
If force is True, or the value of time_fn() is different from
what it was was last time _produce_value was called, a new
value will be produced and returned. Otherwise, the last value
gen produced will be returned.
"""
if hasattr(gen,"_Dynamic_time_fn"):
time_fn = gen._Dynamic_time_fn
else:
time_fn = self.time_fn
if (time_fn is None) or (not self.time_dependent):
value = _produce_value(gen)
gen._Dynamic_last = value
else:
time = time_fn()
if force or time!=gen._Dynamic_time:
value = _produce_value(gen)
gen._Dynamic_last = value
gen._Dynamic_time = time
else:
value = gen._Dynamic_last
return value
def _value_is_dynamic(self,obj,objtype=None):
"""
Return True if the parameter is actually dynamic (i.e. the
value is being generated).
"""
return hasattr(super().__get__(obj,objtype),'_Dynamic_last')
def _inspect(self,obj,objtype=None):
"""Return the last generated value for this parameter."""
gen=super().__get__(obj,objtype)
if hasattr(gen,'_Dynamic_last'):
return gen._Dynamic_last
else:
return gen
def _force(self,obj,objtype=None):
"""Force a new value to be generated, and return it."""
gen=super().__get__(obj,objtype)
if hasattr(gen,'_Dynamic_last'):
return self._produce_value(gen,force=True)
else:
return gen
class __compute_set_hook:
"""Remove when set_hook is removed"""
def __call__(self, p):
return _identity_hook
def __repr__(self):
return repr(self.sig)
@property
def sig(self):
return None
_compute_set_hook = __compute_set_hook()
class Number(Dynamic):
"""
A numeric Dynamic Parameter, with a default value and optional bounds.
There are two types of bounds: ``bounds`` and
``softbounds``. ``bounds`` are hard bounds: the parameter must
have a value within the specified range. The default bounds are
(None,None), meaning there are actually no hard bounds. One or
both bounds can be set by specifying a value
(e.g. bounds=(None,10) means there is no lower bound, and an upper
bound of 10). Bounds are inclusive by default, but exclusivity
can be specified for each bound by setting inclusive_bounds
(e.g. inclusive_bounds=(True,False) specifies an exclusive upper
bound).
Number is also a type of Dynamic parameter, so its value
can be set to a callable to get a dynamically generated
number (see Dynamic).
When not being dynamically generated, bounds are checked when a
Number is created or set. Using a default value outside the hard
bounds, or one that is not numeric, results in an exception. When
being dynamically generated, bounds are checked when the value
of a Number is requested. A generated value that is not numeric,
or is outside the hard bounds, results in an exception.
As a special case, if allow_None=True (which is true by default if
the parameter has a default of None when declared) then a value
of None is also allowed.
A separate function set_in_bounds() is provided that will
silently crop the given value into the legal range, for use
in, for instance, a GUI.
``softbounds`` are present to indicate the typical range of
the parameter, but are not enforced. Setting the soft bounds
allows, for instance, a GUI to know what values to display on
sliders for the Number.
Example of creating a Number::
AB = Number(default=0.5, bounds=(None,10), softbounds=(0,1), doc='Distance from A to B.')
"""
__slots__ = ['bounds', 'softbounds', 'inclusive_bounds', 'set_hook', 'step']
_slot_defaults = _dict_update(
Dynamic._slot_defaults, default=0.0, bounds=None, softbounds=None,
inclusive_bounds=(True,True), step=None, set_hook=_compute_set_hook,
)
@typing.overload
def __init__(
self,
default=0.0, *, bounds=None, softbounds=None, inclusive_bounds=(True,True), step=None, set_hook=None,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, bounds=Undefined, softbounds=Undefined,
inclusive_bounds=Undefined, step=Undefined, set_hook=Undefined, **params):
"""
Initialize this parameter object and store the bounds.
Non-dynamic default values are checked against the bounds.
"""
super().__init__(default=default, **params)
self.set_hook = set_hook
self.bounds = bounds
self.inclusive_bounds = inclusive_bounds
self.softbounds = softbounds
self.step = step
self._validate(self.default)
def __get__(self, obj, objtype):
"""
Same as the superclass's __get__, but if the value was
dynamically generated, check the bounds.
"""
result = super().__get__(obj, objtype)
# Should be able to optimize this commonly used method by
# avoiding extra lookups (e.g. _value_is_dynamic() is also
# looking up 'result' - should just pass it in).
if self._value_is_dynamic(obj, objtype):
self._validate(result)
return result
def set_in_bounds(self,obj,val):
"""
Set to the given value, but cropped to be within the legal bounds.
All objects are accepted, and no exceptions will be raised. See
crop_to_bounds for details on how cropping is done.
"""
if not callable(val):
bounded_val = self.crop_to_bounds(val)
else:
bounded_val = val
super().__set__(obj, bounded_val)
def crop_to_bounds(self, val):
"""
Return the given value cropped to be within the hard bounds
for this parameter.
If a numeric value is passed in, check it is within the hard
bounds. If it is larger than the high bound, return the high
bound. If it's smaller, return the low bound. In either case, the
returned value could be None. If a non-numeric value is passed
in, set to be the default value (which could be None). In no
case is an exception raised; all values are accepted.
As documented in https://github.com/holoviz/param/issues/80,
currently does not respect exclusive bounds, which would
strictly require setting to one less for integer values or
an epsilon less for floats.
"""
# Values outside the bounds are silently cropped to
# be inside the bounds.
if _is_number(val):
if self.bounds is None:
return val
vmin, vmax = self.bounds
if vmin is not None:
if val < vmin:
return vmin
if vmax is not None:
if val > vmax:
return vmax
elif self.allow_None and val is None:
return val
else:
# non-numeric value sent in: reverts to default value
return self.default
return val
def _validate_bounds(self, val, bounds, inclusive_bounds):
if bounds is None or (val is None and self.allow_None) or callable(val):
return
vmin, vmax = bounds
incmin, incmax = inclusive_bounds
if vmax is not None:
if incmax is True:
if not val <= vmax:
raise ValueError(
f"{_validate_error_prefix(self)} must be at most "
f"{vmax}, not {val}."
)
else:
if not val < vmax:
raise ValueError(
f"{_validate_error_prefix(self)} must be less than "
f"{vmax}, not {val}."
)
if vmin is not None:
if incmin is True:
if not val >= vmin:
raise ValueError(
f"{_validate_error_prefix(self)} must be at least "
f"{vmin}, not {val}."
)
else:
if not val > vmin:
raise ValueError(
f"{_validate_error_prefix(self)} must be greater than "
f"{vmin}, not {val}."
)
def _validate_value(self, val, allow_None):
if (allow_None and val is None) or (callable(val) and not inspect.isgeneratorfunction(val)):
return
if not _is_number(val):
raise ValueError(
f"{_validate_error_prefix(self)} only takes numeric values, "
f"not {type(val)}."
)
def _validate_step(self, val, step):
if step is not None and not _is_number(step):
raise ValueError(
f"{_validate_error_prefix(self, 'step')} can only be "
f"None or a numeric value, not {type(step)}."
)
def _validate(self, val):
"""
Checks that the value is numeric and that it is within the hard
bounds; if not, an exception is raised.
"""
self._validate_value(val, self.allow_None)
self._validate_step(val, self.step)
self._validate_bounds(val, self.bounds, self.inclusive_bounds)
def get_soft_bounds(self):
return get_soft_bounds(self.bounds, self.softbounds)
def __setstate__(self,state):
if 'step' not in state:
state['step'] = None
super().__setstate__(state)
class Integer(Number):
"""Numeric Parameter required to be an Integer"""
_slot_defaults = _dict_update(Number._slot_defaults, default=0)
def _validate_value(self, val, allow_None):
if callable(val):
return
if allow_None and val is None:
return
if not isinstance(val, _int_types):
raise ValueError(
f"{_validate_error_prefix(self)} must be an integer, "
f"not {type(val)}."
)
def _validate_step(self, val, step):
if step is not None and not isinstance(step, int):
raise ValueError(
f"{_validate_error_prefix(self, 'step')} can only be "
f"None or an integer value, not {type(step)}."
)
class Magnitude(Number):
"""Numeric Parameter required to be in the range [0.0-1.0]."""
_slot_defaults = _dict_update(Number._slot_defaults, default=1.0, bounds=(0.0,1.0))
@typing.overload
def __init__(
self,
default=1.0, *, bounds=(0.0, 1.0), softbounds=None, inclusive_bounds=(True,True), step=None, set_hook=None,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, *, bounds=Undefined, softbounds=Undefined,
inclusive_bounds=Undefined, step=Undefined, set_hook=Undefined, **params):
super().__init__(
default=default, bounds=bounds, softbounds=softbounds,
inclusive_bounds=inclusive_bounds, step=step, set_hook=set_hook, **params
)
class Date(Number):
"""
Date parameter of datetime or date type.
"""
_slot_defaults = _dict_update(Number._slot_defaults, default=None)
@typing.overload
def __init__(
self,
default=None, *, bounds=None, softbounds=None, inclusive_bounds=(True,True), step=None, set_hook=None,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, **kwargs):
super().__init__(default=default, **kwargs)
def _validate_value(self, val, allow_None):
"""
Checks that the value is numeric and that it is within the hard
bounds; if not, an exception is raised.
"""
if self.allow_None and val is None:
return
if not isinstance(val, dt_types) and not (allow_None and val is None):
raise ValueError(
f"{_validate_error_prefix(self)} only takes datetime and "
f"date types, not {type(val)}."
)
def _validate_step(self, val, step):
if step is not None and not isinstance(step, dt_types):
raise ValueError(
f"{_validate_error_prefix(self, 'step')} can only be None, "
f"a datetime or date type, not {type(step)}."
)
def _validate_bounds(self, val, bounds, inclusive_bounds):
val = _to_datetime(val)
bounds = None if bounds is None else map(_to_datetime, bounds)
return super()._validate_bounds(val, bounds, inclusive_bounds)
@classmethod
def serialize(cls, value):
if value is None:
return None
if not isinstance(value, (dt.datetime, dt.date)): # i.e np.datetime64
value = value.astype(dt.datetime)
return value.strftime("%Y-%m-%dT%H:%M:%S.%f")
@classmethod
def deserialize(cls, value):
if value == 'null' or value is None:
return None
return dt.datetime.strptime(value, "%Y-%m-%dT%H:%M:%S.%f")
class CalendarDate(Number):
"""
Parameter specifically allowing dates (not datetimes).
"""
_slot_defaults = _dict_update(Number._slot_defaults, default=None)
@typing.overload
def __init__(
self,
default=None, *, bounds=None, softbounds=None, inclusive_bounds=(True,True), step=None, set_hook=None,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, **kwargs):
super().__init__(default=default, **kwargs)
def _validate_value(self, val, allow_None):
"""
Checks that the value is numeric and that it is within the hard
bounds; if not, an exception is raised.
"""
if self.allow_None and val is None:
return
if (not isinstance(val, dt.date) or isinstance(val, dt.datetime)) and not (allow_None and val is None):
raise ValueError(
f"{_validate_error_prefix(self)} only takes date types."
)
def _validate_step(self, val, step):
if step is not None and not isinstance(step, dt.date):
raise ValueError(
f"{_validate_error_prefix(self, 'step')} can only be None or "
f"a date type, not {type(step)}."
)
@classmethod
def serialize(cls, value):
if value is None:
return None
return value.strftime("%Y-%m-%d")
@classmethod
def deserialize(cls, value):
if value == 'null' or value is None:
return None
return dt.datetime.strptime(value, "%Y-%m-%d").date()
#-----------------------------------------------------------------------------
# Boolean
#-----------------------------------------------------------------------------
class Boolean(Parameter):
"""Binary or tristate Boolean Parameter."""
_slot_defaults = _dict_update(Parameter._slot_defaults, default=False)
@typing.overload
def __init__(
self,
default=False, *,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, **params):
super().__init__(default=default, **params)
self._validate(self.default)
def _validate_value(self, val, allow_None):
if allow_None:
if not isinstance(val, bool) and val is not None:
raise ValueError(
f"{_validate_error_prefix(self)} only takes a "
f"boolean value or None, not {val!r}."
)
elif not isinstance(val, bool):
raise ValueError(
f"{_validate_error_prefix(self)} must be True or False, "
f"not {val!r}."
)
def _validate(self, val):
self._validate_value(val, self.allow_None)
class Event(Boolean):
"""
An Event Parameter is one whose value is intimately linked to the
triggering of events for watchers to consume. Event has a Boolean
value, which when set to True triggers the associated watchers (as
any Parameter does) and then is automatically set back to
False. Conversely, if events are triggered directly via `.trigger`,
the value is transiently set to True (so that it's clear which of
many parameters being watched may have changed), then restored to
False when the triggering completes. An Event parameter is thus like
a momentary switch or pushbutton with a transient True value that
serves only to launch some other action (e.g. via a param.depends
decorator), rather than encapsulating the action itself as
param.Action does.
"""
# _autotrigger_value specifies the value used to set the parameter
# to when the parameter is supplied to the trigger method. This
# value change is then what triggers the watcher callbacks.
__slots__ = ['_autotrigger_value', '_mode', '_autotrigger_reset_value']
@typing.overload
def __init__(
self,
default=False, *,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self,default=False,**params):
self._autotrigger_value = True
self._autotrigger_reset_value = False
self._mode = 'set-reset'
# Mode can be one of 'set', 'set-reset' or 'reset'
# 'set' is normal Boolean parameter behavior when set with a value.
# 'set-reset' temporarily sets the parameter (which triggers
# watching callbacks) but immediately resets the value back to
# False.
# 'reset' applies the reset from True to False without
# triggering watched callbacks
# This _mode attribute is one of the few places where a specific
# parameter has a special behavior that is relied upon by the
# core functionality implemented in
# parameterized.py. Specifically, the set_param method
# temporarily sets this attribute in order to disable resetting
# back to False while triggered callbacks are executing
super().__init__(default=default,**params)
def _reset_event(self, obj, val):
val = False
if obj is None:
self.default = val
else:
obj._param__private.values[self.name] = val
self._post_setter(obj, val)
@instance_descriptor
def __set__(self, obj, val):
if self._mode in ['set-reset', 'set']:
super().__set__(obj, val)
if self._mode in ['set-reset', 'reset']:
self._reset_event(obj, val)
#-----------------------------------------------------------------------------
# Tuple
#-----------------------------------------------------------------------------
class __compute_length_of_default:
def __call__(self, p):
return len(p.default)
def __repr__(self):
return repr(self.sig)
@property
def sig(self):
return None
_compute_length_of_default = __compute_length_of_default()
class Tuple(Parameter):
"""A tuple Parameter (e.g. ('a',7.6,[3,5])) with a fixed tuple length."""
__slots__ = ['length']
_slot_defaults = _dict_update(Parameter._slot_defaults, default=(0,0), length=_compute_length_of_default)
@typing.overload
def __init__(
self,
default=(0,0), *, length=None,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, length=Undefined, **params):
"""
Initialize a tuple parameter with a fixed length (number of
elements). The length is determined by the initial default
value, if any, and must be supplied explicitly otherwise. The
length is not allowed to change after instantiation.
"""
super().__init__(default=default, **params)
if length is Undefined and self.default is None:
raise ValueError(
f"{_validate_error_prefix(self, 'length')} must be "
"specified if no default is supplied."
)
elif default is not Undefined and default:
self.length = len(default)
else:
self.length = length
self._validate(self.default)
def _validate_value(self, val, allow_None):
if val is None and allow_None:
return
if not isinstance(val, tuple):
raise ValueError(
f"{_validate_error_prefix(self)} only takes a tuple value, "
f"not {type(val)}."
)
def _validate_length(self, val, length):
if val is None and self.allow_None:
return
if not len(val) == length:
raise ValueError(
f"{_validate_error_prefix(self, 'length')} is not "
f"of the correct length ({len(val)} instead of {length})."
)
def _validate(self, val):
self._validate_value(val, self.allow_None)
self._validate_length(val, self.length)
@classmethod
def serialize(cls, value):
if value is None:
return None
return list(value) # As JSON has no tuple representation
@classmethod
def deserialize(cls, value):
if value == 'null' or value is None:
return None
return tuple(value) # As JSON has no tuple representation
class NumericTuple(Tuple):
"""A numeric tuple Parameter (e.g. (4.5,7.6,3)) with a fixed tuple length."""
def _validate_value(self, val, allow_None):
super()._validate_value(val, allow_None)
if allow_None and val is None:
return
for n in val:
if _is_number(n):
continue
raise ValueError(
f"{_validate_error_prefix(self)} only takes numeric "
f"values, not {type(n)}."
)
class XYCoordinates(NumericTuple):
"""A NumericTuple for an X,Y coordinate."""
_slot_defaults = _dict_update(NumericTuple._slot_defaults, default=(0.0, 0.0))
@typing.overload
def __init__(
self,
default=(0.0, 0.0), *, length=None,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, **params):
super().__init__(default=default, length=2, **params)
class Range(NumericTuple):
"""
A numeric range with optional bounds and softbounds.
"""
__slots__ = ['bounds', 'inclusive_bounds', 'softbounds', 'step']
_slot_defaults = _dict_update(
NumericTuple._slot_defaults, default=None, bounds=None,
inclusive_bounds=(True,True), softbounds=None, step=None
)
@typing.overload
def __init__(
self,
default=None, *, bounds=None, softbounds=None, inclusive_bounds=(True,True), step=None, length=None,
doc=None, label=None, precedence=None, instantiate=False, constant=False,
readonly=False, pickle_default_value=True, allow_None=False, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, bounds=Undefined, softbounds=Undefined,
inclusive_bounds=Undefined, step=Undefined, **params):
self.bounds = bounds
self.inclusive_bounds = inclusive_bounds
self.softbounds = softbounds
self.step = step
super().__init__(default=default,length=2,**params)
def _validate(self, val):
super()._validate(val)
self._validate_bounds(val, self.bounds, self.inclusive_bounds, 'bound')
self._validate_bounds(val, self.softbounds, self.inclusive_bounds, 'softbound')
self._validate_step(val, self.step)
self._validate_order(val, self.step, allow_None=self.allow_None)
def _validate_step(self, val, step):
if step is not None:
if not _is_number(step):
raise ValueError(
f"{_validate_error_prefix(self, 'step')} can only be None "
f"or a numeric value, not {type(step)}."
)
elif step == 0:
raise ValueError(
f"{_validate_error_prefix(self, 'step')} cannot be 0."
)
def _validate_order(self, val, step, allow_None):
if val is None and allow_None:
return
elif val is not None and (val[0] is None or val[1] is None):
return
start, end = val
if step is not None and step > 0 and not start <= end:
raise ValueError(
f"{_validate_error_prefix(self)} end {end} is less than its "
f"start {start} with positive step {step}."
)
elif step is not None and step < 0 and not start >= end:
raise ValueError(
f"{_validate_error_prefix(self)} start {start} is less than its "
f"start {end} with negative step {step}."
)
def _validate_bound_type(self, value, position, kind):
if not _is_number(value):
raise ValueError(
f"{_validate_error_prefix(self)} {position} {kind} can only be "
f"None or a numerical value, not {type(value)}."
)
def _validate_bounds(self, val, bounds, inclusive_bounds, kind):
if bounds is not None:
for pos, v in zip(['lower', 'upper'], bounds):
if v is None:
continue
self._validate_bound_type(v, pos, kind)
if kind == 'softbound':
return
if bounds is None or (val is None and self.allow_None):
return
vmin, vmax = bounds
incmin, incmax = inclusive_bounds
for bound, v in zip(['lower', 'upper'], val):
too_low = (vmin is not None) and (v < vmin if incmin else v <= vmin)
too_high = (vmax is not None) and (v > vmax if incmax else v >= vmax)
if too_low or too_high:
raise ValueError(
f"{_validate_error_prefix(self)} {bound} bound must be in "
f"range {self.rangestr()}, not {v}."
)
def get_soft_bounds(self):
return get_soft_bounds(self.bounds, self.softbounds)
def rangestr(self):
vmin, vmax = self.bounds
incmin, incmax = self.inclusive_bounds
incmin = '[' if incmin else '('
incmax = ']' if incmax else ')'
return f'{incmin}{vmin}, {vmax}{incmax}'
class DateRange(Range):
"""
A datetime or date range specified as (start, end).
Bounds must be specified as datetime or date types (see param.dt_types).
"""
def _validate_bound_type(self, value, position, kind):
if not isinstance(value, dt_types):
raise ValueError(
f"{_validate_error_prefix(self)} {position} {kind} can only be "
f"None or a date/datetime value, not {type(value)}."
)
def _validate_bounds(self, val, bounds, inclusive_bounds, kind):
val = None if val is None else tuple(map(_to_datetime, val))
bounds = None if bounds is None else tuple(map(_to_datetime, bounds))
super()._validate_bounds(val, bounds, inclusive_bounds, kind)
def _validate_value(self, val, allow_None):
# Cannot use super()._validate_value as DateRange inherits from
# NumericTuple which check that the tuple values are numbers and
# datetime objects aren't numbers.
if allow_None and val is None:
return
if not isinstance(val, tuple):
raise ValueError(
f"{_validate_error_prefix(self)} only takes a tuple value, "
f"not {type(val)}."
)
for n in val:
if isinstance(n, dt_types):
continue
raise ValueError(
f"{_validate_error_prefix(self)} only takes date/datetime "
f"values, not {type(n)}."
)
start, end = val
if not end >= start:
raise ValueError(
f"{_validate_error_prefix(self)} end datetime {val[1]} "
f"is before start datetime {val[0]}."
)
@classmethod
def serialize(cls, value):
if value is None:
return None
# List as JSON has no tuple representation
serialized = []
for v in value:
if not isinstance(v, (dt.datetime, dt.date)): # i.e np.datetime64
v = v.astype(dt.datetime)
# Separate date and datetime to deserialize to the right type.
if type(v) == dt.date:
v = v.strftime("%Y-%m-%d")
else:
v = v.strftime("%Y-%m-%dT%H:%M:%S.%f")
serialized.append(v)
return serialized
def deserialize(cls, value):
if value == 'null' or value is None:
return None
deserialized = []
for v in value:
# Date
if len(v) == 10:
v = dt.datetime.strptime(v, "%Y-%m-%d").date()
# Datetime
else:
v = dt.datetime.strptime(v, "%Y-%m-%dT%H:%M:%S.%f")
deserialized.append(v)
# As JSON has no tuple representation
return tuple(deserialized)
class CalendarDateRange(Range):
"""
A date range specified as (start_date, end_date).
"""
def _validate_value(self, val, allow_None):
if allow_None and val is None:
return
for n in val:
if not isinstance(n, dt.date):
raise ValueError(
f"{_validate_error_prefix(self)} only takes date types, "
f"not {val}."
)
start, end = val
if not end >= start:
raise ValueError(
f"{_validate_error_prefix(self)} end date {val[1]} is before "
f"start date {val[0]}."
)
def _validate_bound_type(self, value, position, kind):
if not isinstance(value, dt.date):
raise ValueError(
f"{_validate_error_prefix(self)} {position} {kind} can only be "
f"None or a date value, not {type(value)}."
)
@classmethod
def serialize(cls, value):
if value is None:
return None
# As JSON has no tuple representation
return [v.strftime("%Y-%m-%d") for v in value]
@classmethod
def deserialize(cls, value):
if value == 'null' or value is None:
return None
# As JSON has no tuple representation
return tuple([dt.datetime.strptime(v, "%Y-%m-%d").date() for v in value])
#-----------------------------------------------------------------------------
# Callable
#-----------------------------------------------------------------------------
class Callable(Parameter):
"""
Parameter holding a value that is a callable object, such as a function.
A keyword argument instantiate=True should be provided when a
function object is used that might have state. On the other hand,
regular standalone functions cannot be deepcopied as of Python
2.4, so instantiate must be False for those values.
"""
@typing.overload
def __init__(
self,
default=None, *,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, **params):
super().__init__(default=default, **params)
self._validate(self.default)
def _validate_value(self, val, allow_None):
if (allow_None and val is None) or callable(val):
return
raise ValueError(
f"{_validate_error_prefix(self)} only takes a callable object, "
f"not objects of {type(val)}."
)
def _validate(self, val):
self._validate_value(val, self.allow_None)
class Action(Callable):
"""
A user-provided function that can be invoked like a class or object method using ().
In a GUI, this might be mapped to a button, but it can be invoked directly as well.
"""
# Currently same implementation as Callable, but kept separate to allow different handling in GUIs
#-----------------------------------------------------------------------------
# Composite
#-----------------------------------------------------------------------------
class Composite(Parameter):
"""
A Parameter that is a composite of a set of other attributes of the class.
The constructor argument 'attribs' takes a list of attribute
names, which may or may not be Parameters. Getting the parameter
returns a list of the values of the constituents of the composite,
in the order specified. Likewise, setting the parameter takes a
sequence of values and sets the value of the constituent
attributes.
This Parameter type has not been tested with watchers and
dependencies, and may not support them properly.
"""
__slots__ = ['attribs', 'objtype']
@typing.overload
def __init__(
self,
*, attribs=None,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, *, attribs=Undefined, **kw):
if attribs is Undefined:
attribs = []
super().__init__(default=Undefined, **kw)
self.attribs = attribs
def __get__(self, obj, objtype):
"""
Return the values of all the attribs, as a list.
"""
if obj is None:
return [getattr(objtype, a) for a in self.attribs]
else:
return [getattr(obj, a) for a in self.attribs]
def _validate_attribs(self, val, attribs):
if len(val) == len(attribs):
return
raise ValueError(
f"{_validate_error_prefix(self)} got the wrong number "
f"of values (needed {len(attribs)}, but got {len(val)})."
)
def _validate(self, val):
self._validate_attribs(val, self.attribs)
def _post_setter(self, obj, val):
if obj is None:
for a, v in zip(self.attribs, val):
setattr(self.objtype, a, v)
else:
for a, v in zip(self.attribs, val):
setattr(obj, a, v)
#-----------------------------------------------------------------------------
# Selector
#-----------------------------------------------------------------------------
class SelectorBase(Parameter):
"""
Parameter whose value must be chosen from a list of possibilities.
Subclasses must implement get_range().
"""
__abstract = True
def get_range(self):
raise NotImplementedError("get_range() must be implemented in subclasses.")
class ListProxy(list):
"""
Container that supports both list-style and dictionary-style
updates. Useful for replacing code that originally accepted lists
but needs to support dictionary access (typically for naming
items).
"""
def __init__(self, iterable, parameter=None):
super().__init__(iterable)
self._parameter = parameter
def _warn(self, method):
clsname = type(self._parameter).__name__
get_logger().warning(
'{clsname}.objects{method} is deprecated if objects attribute '
'was declared as a dictionary. Use `{clsname}.objects[label] '
'= value` instead.'.format(clsname=clsname, method=method)
)
@contextmanager
def _trigger(self, trigger=True):
trigger = 'objects' in self._parameter.watchers and trigger
old = dict(self._parameter.names) or list(self._parameter._objects)
yield
if trigger:
value = self._parameter.names or self._parameter._objects
self._parameter._trigger_event('objects', old, value)
def __getitem__(self, index):
if self._parameter.names:
return self._parameter.names[index]
return super().__getitem__(index)
def __setitem__(self, index, object, trigger=True):
if isinstance(index, (int, slice)):
if self._parameter.names:
self._warn('[index] = object')
with self._trigger():
super().__setitem__(index, object)
self._parameter._objects[index] = object
return
if self and not self._parameter.names:
self._parameter.names = _named_objs(self)
with self._trigger(trigger):
if index in self._parameter.names:
old = self._parameter.names[index]
idx = self.index(old)
super().__setitem__(idx, object)
self._parameter._objects[idx] = object
else:
super().append(object)
self._parameter._objects.append(object)
self._parameter.names[index] = object
def __eq__(self, other):
eq = super().__eq__(other)
if self._parameter.names and eq is NotImplemented:
return dict(zip(self._parameter.names, self)) == other
return eq
def __ne__(self, other):
return not self.__eq__(other)
def append(self, object):
if self._parameter.names:
self._warn('.append')
with self._trigger():
super().append(object)
self._parameter._objects.append(object)
def copy(self):
if self._parameter.names:
return self._parameter.names.copy()
return list(self)
def clear(self):
with self._trigger():
super().clear()
self._parameter._objects.clear()
self._parameter.names.clear()
def extend(self, objects):
if self._parameter.names:
self._warn('.append')
with self._trigger():
super().extend(objects)
self._parameter._objects.extend(objects)
def get(self, key, default=None):
if self._parameter.names:
return self._parameter.names.get(key, default)
return _named_objs(self).get(key, default)
def insert(self, index, object):
if self._parameter.names:
self._warn('.insert')
with self._trigger():
super().insert(index, object)
self._parameter._objects.insert(index, object)
def items(self):
if self._parameter.names:
return self._parameter.names.items()
return _named_objs(self).items()
def keys(self):
if self._parameter.names:
return self._parameter.names.keys()
return _named_objs(self).keys()
def pop(self, *args):
index = args[0] if args else -1
if isinstance(index, int):
with self._trigger():
super().pop(index)
object = self._parameter._objects.pop(index)
if self._parameter.names:
self._parameter.names = {
k: v for k, v in self._parameter.names.items()
if v is object
}
return
if self and not self._parameter.names:
raise ValueError(
'Cannot pop an object from {clsname}.objects if '
'objects was not declared as a dictionary.'
)
with self._trigger():
object = self._parameter.names.pop(*args)
super().remove(object)
self._parameter._objects.remove(object)
return object
def remove(self, object):
with self._trigger():
super().remove(object)
self._parameter._objects.remove(object)
if self._parameter.names:
copy = self._parameter.names.copy()
self._parameter.names.clear()
self._parameter.names.update({
k: v for k, v in copy.items() if v is not object
})
def update(self, objects, **items):
if not self._parameter.names:
self._parameter.names = _named_objs(self)
objects = objects.items() if isinstance(objects, dict) else objects
with self._trigger():
for i, o in enumerate(objects):
if not isinstance(o, collections.abc.Sequence):
raise TypeError(
f'cannot convert dictionary update sequence element #{i} to a sequence'
)
o = tuple(o)
n = len(o)
if n != 2:
raise ValueError(
f'dictionary update sequence element #{i} has length {n}; 2 is required'
)
k, v = o
self.__setitem__(k, v, trigger=False)
for k, v in items.items():
self.__setitem__(k, v, trigger=False)
def values(self):
if self._parameter.names:
return self._parameter.names.values()
return _named_objs(self).values()
class __compute_selector_default:
"""
Using a function instead of setting default to [] in _slot_defaults, as
if it were modified in place later, which would happen with check_on_set set to False,
then the object in _slot_defaults would itself be updated and the next Selector
instance created wouldn't have [] as the default but a populated list.
"""
def __call__(self, p):
return []
def __repr__(self):
return repr(self.sig)
@property
def sig(self):
return []
_compute_selector_default = __compute_selector_default()
class __compute_selector_checking_default:
def __call__(self, p):
return len(p.objects) != 0
def __repr__(self):
return repr(self.sig)
@property
def sig(self):
return None
_compute_selector_checking_default = __compute_selector_checking_default()
class _SignatureSelector(Parameter):
# Needs docstring; why is this a separate mixin?
_slot_defaults = _dict_update(
SelectorBase._slot_defaults, _objects=_compute_selector_default,
compute_default_fn=None, check_on_set=_compute_selector_checking_default,
allow_None=None, instantiate=False, default=None,
)
@classmethod
def _modified_slots_defaults(cls):
defaults = super()._modified_slots_defaults()
defaults['objects'] = defaults.pop('_objects')
return defaults
class Selector(SelectorBase, _SignatureSelector):
"""
Parameter whose value must be one object from a list of possible objects.
By default, if no default is specified, picks the first object from
the provided set of objects, as long as the objects are in an
ordered data collection.
check_on_set restricts the value to be among the current list of
objects. By default, if objects are initially supplied,
check_on_set is True, whereas if no objects are initially
supplied, check_on_set is False. This can be overridden by
explicitly specifying check_on_set initially.
If check_on_set is True (either because objects are supplied
initially, or because it is explicitly specified), the default
(initial) value must be among the list of objects (unless the
default value is None).
The list of objects can be supplied as a list (appropriate for
selecting among a set of strings, or among a set of objects with a
"name" parameter), or as a (preferably ordered) dictionary from
names to objects. If a dictionary is supplied, the objects
will need to be hashable so that their names can be looked
up from the object value.
empty_default is an internal argument that does not have a slot.
"""
__slots__ = ['_objects', 'compute_default_fn', 'check_on_set', 'names']
@typing.overload
def __init__(
self,
*, objects=[], default=None, instantiate=False, compute_default_fn=None,
check_on_set=None, allow_None=None, empty_default=False,
doc=None, label=None, precedence=None, constant=False, readonly=False,
pickle_default_value=True, per_instance=True, allow_refs=False, nested_refs=False
):
...
# Selector is usually used to allow selection from a list of
# existing objects, therefore instantiate is False by default.
@_deprecate_positional_args
def __init__(self, *, objects=Undefined, default=Undefined, instantiate=Undefined,
compute_default_fn=Undefined, check_on_set=Undefined,
allow_None=Undefined, empty_default=False, **params):
autodefault = Undefined
if objects is not Undefined and objects:
if isinstance(objects, dict):
autodefault = list(objects.values())[0]
elif isinstance(objects, list):
autodefault = objects[0]
default = autodefault if (not empty_default and default is Undefined) else default
self.objects = objects
self.compute_default_fn = compute_default_fn
self.check_on_set = check_on_set
super().__init__(
default=default, instantiate=instantiate, **params)
# Required as Parameter sets allow_None=True if default is None
if allow_None is Undefined:
self.allow_None = self._slot_defaults['allow_None']
else:
self.allow_None = allow_None
if self.default is not None:
self._validate_value(self.default)
self._update_state()
def _update_state(self):
if self.check_on_set is False and self.default is not None:
self._ensure_value_is_in_objects(self.default)
@property
def objects(self):
return ListProxy(self._objects, self)
@objects.setter
def objects(self, objects):
if isinstance(objects, collections.abc.Mapping):
self.names = objects
self._objects = list(objects.values())
else:
self.names = {}
self._objects = objects
# Note that if the list of objects is changed, the current value for
# this parameter in existing POs could be outside of the new range.
def compute_default(self):
"""
If this parameter's compute_default_fn is callable, call it
and store the result in self.default.
Also removes None from the list of objects (if the default is
no longer None).
"""
if self.default is None and callable(self.compute_default_fn):
self.default = self.compute_default_fn()
self._ensure_value_is_in_objects(self.default)
def _validate(self, val):
if not self.check_on_set:
self._ensure_value_is_in_objects(val)
return
self._validate_value(val)
def _validate_value(self, val):
if self.check_on_set and not (self.allow_None and val is None) and val not in self.objects:
items = []
limiter = ']'
length = 0
for item in self.objects:
string = str(item)
length += len(string)
if length < 200:
items.append(string)
else:
limiter = ', ...]'
break
items = '[' + ', '.join(items) + limiter
raise ValueError(
f"{_validate_error_prefix(self)} does not accept {val!r}; "
f"valid options include: {items!r}"
)
def _ensure_value_is_in_objects(self, val):
"""
Make sure that the provided value is present on the objects list.
Subclasses can override if they support multiple items on a list,
to check each item instead.
"""
if not (val in self.objects):
self._objects.append(val)
def get_range(self):
"""
Return the possible objects to which this parameter could be set.
(Returns the dictionary {object.name: object}.)
"""
return _named_objs(self._objects, self.names)
class ObjectSelector(Selector):
"""
Deprecated. Same as Selector, but with a different constructor for
historical reasons.
"""
@typing.overload
def __init__(
self,
default=None, *, objects=[], instantiate=False, compute_default_fn=None,
check_on_set=None, allow_None=None, empty_default=False,
doc=None, label=None, precedence=None, constant=False, readonly=False,
pickle_default_value=True, per_instance=True, allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, objects=Undefined, **kwargs):
super().__init__(objects=objects, default=default,
empty_default=True, **kwargs)
class FileSelector(Selector):
"""
Given a path glob, allows one file to be selected from those matching.
"""
__slots__ = ['path']
_slot_defaults = _dict_update(
Selector._slot_defaults, path="",
)
@typing.overload
def __init__(
self,
default=None, *, path="", objects=[], instantiate=False, compute_default_fn=None,
check_on_set=None, allow_None=None, empty_default=False,
doc=None, label=None, precedence=None, constant=False, readonly=False,
pickle_default_value=True, per_instance=True, allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, path=Undefined, **kwargs):
self.default = default
self.path = path
self.update(path=path)
if default is not Undefined:
self.default = default
super().__init__(default=self.default, objects=self._objects, **kwargs)
def _on_set(self, attribute, old, new):
super()._on_set(attribute, new, old)
if attribute == 'path':
self.update(path=new)
def update(self, path=Undefined):
if path is Undefined:
path = self.path
if path == "":
self.objects = []
else:
# Convert using os.fspath and pathlib.Path to handle ensure
# the path separators are consistent (on Windows in particular)
pathpattern = os.fspath(pathlib.Path(path))
self.objects = sorted(glob.glob(pathpattern))
if self.default in self.objects:
return
self.default = self.objects[0] if self.objects else None
def get_range(self):
return _abbreviate_paths(self.path,super().get_range())
class ListSelector(Selector):
"""
Variant of Selector where the value can be multiple objects from
a list of possible objects.
"""
@typing.overload
def __init__(
self,
default=None, *, objects=[], instantiate=False, compute_default_fn=None,
check_on_set=None, allow_None=None, empty_default=False,
doc=None, label=None, precedence=None, constant=False, readonly=False,
pickle_default_value=True, per_instance=True, allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, objects=Undefined, **kwargs):
super().__init__(
objects=objects, default=default, empty_default=True, **kwargs)
def compute_default(self):
if self.default is None and callable(self.compute_default_fn):
self.default = self.compute_default_fn()
for o in self.default:
if o not in self.objects:
self.objects.append(o)
def _validate(self, val):
if (val is None and self.allow_None):
return
self._validate_type(val)
if self.check_on_set:
self._validate_value(val)
else:
for v in val:
self._ensure_value_is_in_objects(v)
def _validate_type(self, val):
if not isinstance(val, list):
raise ValueError(
f"{_validate_error_prefix(self)} only takes list types, "
f"not {val!r}."
)
def _validate_value(self, val):
self._validate_type(val)
if val is not None:
for o in val:
super()._validate_value(o)
def _update_state(self):
if self.check_on_set is False and self.default is not None:
for o in self.default:
self._ensure_value_is_in_objects(o)
class MultiFileSelector(ListSelector):
"""
Given a path glob, allows multiple files to be selected from the list of matches.
"""
__slots__ = ['path']
_slot_defaults = _dict_update(
Selector._slot_defaults, path="",
)
@typing.overload
def __init__(
self,
default=None, *, path="", objects=[], compute_default_fn=None,
check_on_set=None, allow_None=None, empty_default=False,
doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True,
per_instance=True, allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, path=Undefined, **kwargs):
self.default = default
self.path = path
self.update(path=path)
super().__init__(default=default, objects=self._objects, **kwargs)
def _on_set(self, attribute, old, new):
super()._on_set(attribute, new, old)
if attribute == 'path':
self.update(path=new)
def update(self, path=Undefined):
if path is Undefined:
path = self.path
self.objects = sorted(glob.glob(path))
if self.default and all([o in self.objects for o in self.default]):
return
elif not self.default:
return
self.default = self.objects
def get_range(self):
return _abbreviate_paths(self.path,super().get_range())
class ClassSelector(SelectorBase):
"""
Parameter allowing selection of either a subclass or an instance of a class or tuple of classes.
By default, requires an instance, but if is_instance=False, accepts a class instead.
Both class and instance values respect the instantiate slot, though it matters only
for is_instance=True.
"""
__slots__ = ['class_', 'is_instance']
_slot_defaults = _dict_update(SelectorBase._slot_defaults, instantiate=True, is_instance=True)
@typing.overload
def __init__(
self,
*, class_, default=None, instantiate=True, is_instance=True,
allow_None=False, doc=None, label=None, precedence=None,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, *, class_, default=Undefined, instantiate=Undefined, is_instance=Undefined, **params):
self.class_ = class_
self.is_instance = is_instance
super().__init__(default=default,instantiate=instantiate,**params)
self._validate(self.default)
def _validate(self, val):
super()._validate(val)
self._validate_class_(val, self.class_, self.is_instance)
def _validate_class_(self, val, class_, is_instance):
if (val is None and self.allow_None):
return
if isinstance(class_, tuple):
class_name = ('(%s)' % ', '.join(cl.__name__ for cl in class_))
else:
class_name = class_.__name__
if is_instance:
if not (isinstance(val, class_)):
raise ValueError(
f"{_validate_error_prefix(self)} value must be an instance of {class_name}, not {val!r}.")
else:
if not (issubclass(val, class_)):
raise ValueError(
f"{_validate_error_prefix(self)} value must be a subclass of {class_name}, not {val}.")
def get_range(self):
"""
Return the possible types for this parameter's value.
(I.e. return `{name: }` for all classes that are
concrete_descendents() of `self.class_`.)
Only classes from modules that have been imported are added
(see concrete_descendents()).
"""
classes = self.class_ if isinstance(self.class_, tuple) else (self.class_,)
all_classes = {}
for cls in classes:
all_classes.update(concrete_descendents(cls))
d = OrderedDict((name, class_) for name,class_ in all_classes.items())
if self.allow_None:
d['None'] = None
return d
class Dict(ClassSelector):
"""
Parameter whose value is a dictionary.
"""
@typing.overload
def __init__(
self,
default=None, *, is_instance=True,
allow_None=False, doc=None, label=None, precedence=None, instantiate=True,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, **params):
super().__init__(default=default, class_=dict, **params)
class Array(ClassSelector):
"""
Parameter whose value is a numpy array.
"""
@typing.overload
def __init__(
self,
default=None, *, is_instance=True,
allow_None=False, doc=None, label=None, precedence=None, instantiate=True,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
def __init__(self, default=Undefined, **params):
from numpy import ndarray
super().__init__(default=default, class_=ndarray, **params)
@classmethod
def serialize(cls, value):
if value is None:
return None
return value.tolist()
@classmethod
def deserialize(cls, value):
if value == 'null' or value is None:
return None
import numpy
if isinstance(value, str):
return _deserialize_from_path(
{'.npy': numpy.load, '.txt': lambda x: numpy.loadtxt(str(x))},
value, 'Array'
)
else:
return numpy.asarray(value)
class DataFrame(ClassSelector):
"""
Parameter whose value is a pandas DataFrame.
The structure of the DataFrame can be constrained by the rows and
columns arguments:
rows: If specified, may be a number or an integer bounds tuple to
constrain the allowable number of rows.
columns: If specified, may be a number, an integer bounds tuple, a
list or a set. If the argument is numeric, constrains the number of
columns using the same semantics as used for rows. If either a list
or set of strings, the column names will be validated. If a set is
used, the supplied DataFrame must contain the specified columns and
if a list is given, the supplied DataFrame must contain exactly the
same columns and in the same order and no other columns.
"""
__slots__ = ['rows', 'columns', 'ordered']
_slot_defaults = _dict_update(
ClassSelector._slot_defaults, rows=None, columns=None, ordered=None
)
@typing.overload
def __init__(
self,
default=None, *, rows=None, columns=None, ordered=None, is_instance=True,
allow_None=False, doc=None, label=None, precedence=None, instantiate=True,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, rows=Undefined, columns=Undefined, ordered=Undefined, **params):
from pandas import DataFrame as pdDFrame
self.rows = rows
self.columns = columns
self.ordered = ordered
super().__init__(default=default, class_=pdDFrame, **params)
self._validate(self.default)
def _length_bounds_check(self, bounds, length, name):
message = f'{name} length {length} does not match declared bounds of {bounds}'
if not isinstance(bounds, tuple):
if (bounds != length):
raise ValueError(f"{_validate_error_prefix(self)}: {message}")
else:
return
(lower, upper) = bounds
failure = ((lower is not None and (length < lower))
or (upper is not None and length > upper))
if failure:
raise ValueError(f"{_validate_error_prefix(self)}: {message}")
def _validate(self, val):
super()._validate(val)
if isinstance(self.columns, set) and self.ordered is True:
raise ValueError(
f'{_validate_error_prefix(self)}: columns cannot be ordered '
f'when specified as a set'
)
if self.allow_None and val is None:
return
if self.columns is None:
pass
elif (isinstance(self.columns, tuple) and len(self.columns)==2
and all(isinstance(v, (type(None), numbers.Number)) for v in self.columns)): # Numeric bounds tuple
self._length_bounds_check(self.columns, len(val.columns), 'columns')
elif isinstance(self.columns, (list, set)):
self.ordered = isinstance(self.columns, list) if self.ordered is None else self.ordered
difference = set(self.columns) - {str(el) for el in val.columns}
if difference:
raise ValueError(
f"{_validate_error_prefix(self)}: provided columns "
f"{list(val.columns)} does not contain required "
f"columns {sorted(self.columns)}"
)
else:
self._length_bounds_check(self.columns, len(val.columns), 'column')
if self.ordered:
if list(val.columns) != list(self.columns):
raise ValueError(
f"{_validate_error_prefix(self)}: provided columns "
f"{list(val.columns)} must exactly match {self.columns}"
)
if self.rows is not None:
self._length_bounds_check(self.rows, len(val), 'row')
@classmethod
def serialize(cls, value):
if value is None:
return None
return value.to_dict('records')
@classmethod
def deserialize(cls, value):
if value == 'null' or value is None:
return None
import pandas
if isinstance(value, str):
return _deserialize_from_path(
{
'.csv': pandas.read_csv,
'.dta': pandas.read_stata,
'.feather': pandas.read_feather,
'.h5': pandas.read_hdf,
'.hdf5': pandas.read_hdf,
'.json': pandas.read_json,
'.ods': pandas.read_excel,
'.parquet': pandas.read_parquet,
'.pkl': pandas.read_pickle,
'.tsv': lambda x: pandas.read_csv(x, sep='\t'),
'.xlsm': pandas.read_excel,
'.xlsx': pandas.read_excel,
}, value, 'DataFrame')
else:
return pandas.DataFrame(value)
class Series(ClassSelector):
"""
Parameter whose value is a pandas Series.
The structure of the Series can be constrained by the rows argument
which may be a number or an integer bounds tuple to constrain the
allowable number of rows.
"""
__slots__ = ['rows']
_slot_defaults = _dict_update(
ClassSelector._slot_defaults, rows=None, allow_None=False
)
@typing.overload
def __init__(
self,
default=None, *, rows=None, allow_None=False, is_instance=True,
doc=None, label=None, precedence=None, instantiate=True,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, rows=Undefined, allow_None=Undefined, **params):
from pandas import Series as pdSeries
self.rows = rows
super().__init__(default=default, class_=pdSeries, allow_None=allow_None,
**params)
self._validate(self.default)
def _length_bounds_check(self, bounds, length, name):
message = f'{name} length {length} does not match declared bounds of {bounds}'
if not isinstance(bounds, tuple):
if (bounds != length):
raise ValueError(f"{_validate_error_prefix(self)}: {message}")
else:
return
(lower, upper) = bounds
failure = ((lower is not None and (length < lower))
or (upper is not None and length > upper))
if failure:
raise ValueError(f"{_validate_error_prefix(self)}: {message}")
def _validate(self, val):
super()._validate(val)
if self.allow_None and val is None:
return
if self.rows is not None:
self._length_bounds_check(self.rows, len(val), 'row')
#-----------------------------------------------------------------------------
# List
#-----------------------------------------------------------------------------
class List(Parameter):
"""
Parameter whose value is a list of objects, usually of a specified type.
The bounds allow a minimum and/or maximum length of
list to be enforced. If the item_type is non-None, all
items in the list are checked to be of that type.
`class_` is accepted as an alias for `item_type`, but is
deprecated due to conflict with how the `class_` slot is
used in Selector classes.
"""
__slots__ = ['bounds', 'item_type', 'class_']
_slot_defaults = _dict_update(
Parameter._slot_defaults, class_=None, item_type=None, bounds=(0, None),
instantiate=True, default=[],
)
@typing.overload
def __init__(
self,
default=[], *, class_=None, item_type=None, instantiate=True, bounds=(0, None),
allow_None=False, doc=None, label=None, precedence=None,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, class_=Undefined, item_type=Undefined,
instantiate=Undefined, bounds=Undefined, **params):
if class_ is not Undefined:
# PARAM3_DEPRECATION
warnings.warn(
message="The 'class_' attribute on 'List' is deprecated. Use instead 'item_type'",
category=_ParamDeprecationWarning,
stacklevel=3,
)
if item_type is not Undefined and class_ is not Undefined:
self.item_type = item_type
elif item_type is Undefined or item_type is None:
self.item_type = class_
else:
self.item_type = item_type
self.class_ = self.item_type
self.bounds = bounds
Parameter.__init__(self, default=default, instantiate=instantiate,
**params)
self._validate(self.default)
def _validate(self, val):
"""
Checks that the value is numeric and that it is within the hard
bounds; if not, an exception is raised.
"""
self._validate_value(val, self.allow_None)
self._validate_bounds(val, self.bounds)
self._validate_item_type(val, self.item_type)
def _validate_bounds(self, val, bounds):
"Checks that the list is of the right length and has the right contents."
if bounds is None or (val is None and self.allow_None):
return
min_length, max_length = bounds
l = len(val)
if min_length is not None and max_length is not None:
if not (min_length <= l <= max_length):
raise ValueError(
f"{_validate_error_prefix(self)} length must be between "
f"{min_length} and {max_length} (inclusive), not {l}."
)
elif min_length is not None:
if not min_length <= l:
raise ValueError(
f"{_validate_error_prefix(self)} length must be at "
f"least {min_length}, not {l}."
)
elif max_length is not None:
if not l <= max_length:
raise ValueError(
f"{_validate_error_prefix(self)} length must be at "
f"most {max_length}, not {l}."
)
def _validate_value(self, val, allow_None):
if allow_None and val is None:
return
if not isinstance(val, list):
raise ValueError(
f"{_validate_error_prefix(self)} must be a list, not an "
f"object of {type(val)}."
)
def _validate_item_type(self, val, item_type):
if item_type is None or (self.allow_None and val is None):
return
for v in val:
if isinstance(v, item_type):
continue
raise TypeError(
f"{_validate_error_prefix(self)} items must be instances "
f"of {item_type!r}, not {type(v)}."
)
class HookList(List):
"""
Parameter whose value is a list of callable objects.
This type of List Parameter is typically used to provide a place
for users to register a set of commands to be called at a
specified place in some sequence of processing steps.
"""
__slots__ = ['class_', 'bounds']
def _validate_value(self, val, allow_None):
super()._validate_value(val, allow_None)
if allow_None and val is None:
return
for v in val:
if callable(v):
continue
raise ValueError(
f"{_validate_error_prefix(self)} items must be callable, "
f"not {v!r}."
)
#-----------------------------------------------------------------------------
# Path
#-----------------------------------------------------------------------------
# For portable code:
# - specify paths in unix (rather than Windows) style;
# - use resolve_path(path_to_file=True) for paths to existing files to be read,
# - use resolve_path(path_to_file=False) for paths to existing folders to be read,
# and normalize_path() for paths to new files to be written.
class resolve_path(ParameterizedFunction):
"""
Find the path to an existing file, searching the paths specified
in the search_paths parameter if the filename is not absolute, and
converting a UNIX-style path to the current OS's format if
necessary.
To turn a supplied relative path into an absolute one, the path is
appended to paths in the search_paths parameter, in order, until
the file is found.
An IOError is raised if the file is not found.
Similar to Python's os.path.abspath(), except more search paths
than just os.getcwd() can be used, and the file must exist.
"""
search_paths = List(default=[os.getcwd()], pickle_default_value=False, doc="""
Prepended to a non-relative path, in order, until a file is
found.""")
path_to_file = Boolean(default=True, pickle_default_value=False,
allow_None=True, doc="""
String specifying whether the path refers to a 'File' or a
'Folder'. If None, the path may point to *either* a 'File' *or*
a 'Folder'.""")
def __call__(self, path, **params):
p = ParamOverrides(self, params)
path = os.path.normpath(path)
ftype = "File" if p.path_to_file is True \
else "Folder" if p.path_to_file is False else "Path"
if not p.search_paths:
p.search_paths = [os.getcwd()]
if os.path.isabs(path):
if ((p.path_to_file is None and os.path.exists(path)) or
(p.path_to_file is True and os.path.isfile(path)) or
(p.path_to_file is False and os.path.isdir( path))):
return path
raise OSError(f"{ftype} '{path}' not found.")
else:
paths_tried = []
for prefix in p.search_paths:
try_path = os.path.join(os.path.normpath(prefix), path)
if ((p.path_to_file is None and os.path.exists(try_path)) or
(p.path_to_file is True and os.path.isfile(try_path)) or
(p.path_to_file is False and os.path.isdir( try_path))):
return try_path
paths_tried.append(try_path)
raise OSError(ftype + " " + os.path.split(path)[1] + " was not found in the following place(s): " + str(paths_tried) + ".")
# PARAM3_DEPRECATION
@_deprecated()
class normalize_path(ParameterizedFunction):
"""
Convert a UNIX-style path to the current OS's format,
typically for creating a new file or directory.
If the path is not already absolute, it will be made absolute
(using the prefix parameter).
Should do the same as Python's os.path.abspath(), except using
prefix rather than os.getcwd).
"""
prefix = String(default=os.getcwd(),pickle_default_value=False,doc="""
Prepended to the specified path, if that path is not
absolute.""")
def __call__(self,path="",**params):
p = ParamOverrides(self,params)
if not os.path.isabs(path):
path = os.path.join(os.path.normpath(p.prefix),path)
return os.path.normpath(path)
class Path(Parameter):
"""Parameter that can be set to a string specifying the path of a file or folder.
The string should be specified in UNIX style, but it will be
returned in the format of the user's operating system. Please use
the Filename or Foldername Parameters if you require discrimination
between the two possibilities.
The specified path can be absolute, or relative to either:
* any of the paths specified in the search_paths attribute (if
search_paths is not None);
or
* any of the paths searched by resolve_path() (if search_paths
is None).
Parameters
----------
search_paths : list, default=[os.getcwd()]
List of paths to search the path from
check_exists: boolean, default=True
If True (default) the path must exist on instantiation and set,
otherwise the path can optionally exist.
"""
__slots__ = ['search_paths', 'check_exists']
_slot_defaults = _dict_update(
Parameter._slot_defaults, check_exists=True,
)
@typing.overload
def __init__(
self,
default=None, *, search_paths=None, check_exists=True,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, search_paths=Undefined, check_exists=Undefined, **params):
if search_paths is Undefined:
search_paths = []
self.search_paths = search_paths
if check_exists is not Undefined and not isinstance(check_exists, bool):
raise ValueError("'check_exists' attribute value must be a boolean")
self.check_exists = check_exists
super().__init__(default,**params)
self._validate(self.default)
def _resolve(self, path):
return resolve_path(path, path_to_file=None, search_paths=self.search_paths)
def _validate(self, val):
if val is None:
if not self.allow_None:
raise ValueError(f'{_validate_error_prefix(self)} does not accept None')
else:
if not isinstance(val, (str, pathlib.Path)):
raise ValueError(f'{_validate_error_prefix(self)} only take str or pathlib.Path types')
try:
self._resolve(val)
except OSError as e:
if self.check_exists:
raise OSError(e.args[0]) from None
def __get__(self, obj, objtype):
"""
Return an absolute, normalized path (see resolve_path).
"""
raw_path = super().__get__(obj,objtype)
if raw_path is None:
path = None
else:
try:
path = self._resolve(raw_path)
except OSError:
if self.check_exists:
raise
else:
path = raw_path
return path
def __getstate__(self):
# don't want to pickle the search_paths
state = super().__getstate__()
if 'search_paths' in state:
state['search_paths'] = []
return state
class Filename(Path):
"""
Parameter that can be set to a string specifying the path of a file.
The string should be specified in UNIX style, but it will be
returned in the format of the user's operating system.
The specified path can be absolute, or relative to either:
* any of the paths specified in the search_paths attribute (if
search_paths is not None);
or
* any of the paths searched by resolve_path() (if search_paths
is None).
"""
def _resolve(self, path):
return resolve_path(path, path_to_file=True, search_paths=self.search_paths)
class Foldername(Path):
"""
Parameter that can be set to a string specifying the path of a folder.
The string should be specified in UNIX style, but it will be
returned in the format of the user's operating system.
The specified path can be absolute, or relative to either:
* any of the paths specified in the search_paths attribute (if
search_paths is not None);
or
* any of the paths searched by resolve_dir_path() (if search_paths
is None).
"""
def _resolve(self, path):
return resolve_path(path, path_to_file=False, search_paths=self.search_paths)
#-----------------------------------------------------------------------------
# Color
#-----------------------------------------------------------------------------
class Color(Parameter):
"""
Color parameter defined as a hex RGB string with an optional #
prefix or (optionally) as a CSS3 color name.
"""
# CSS3 color specification https://www.w3.org/TR/css-color-3/#svg-color
_named_colors = [ 'aliceblue', 'antiquewhite', 'aqua',
'aquamarine', 'azure', 'beige', 'bisque', 'black',
'blanchedalmond', 'blue', 'blueviolet', 'brown', 'burlywood',
'cadetblue', 'chartreuse', 'chocolate', 'coral',
'cornflowerblue', 'cornsilk', 'crimson', 'cyan', 'darkblue',
'darkcyan', 'darkgoldenrod', 'darkgray', 'darkgrey',
'darkgreen', 'darkkhaki', 'darkmagenta', 'darkolivegreen',
'darkorange', 'darkorchid', 'darkred', 'darksalmon',
'darkseagreen', 'darkslateblue', 'darkslategray',
'darkslategrey', 'darkturquoise', 'darkviolet', 'deeppink',
'deepskyblue', 'dimgray', 'dimgrey', 'dodgerblue',
'firebrick', 'floralwhite', 'forestgreen', 'fuchsia',
'gainsboro', 'ghostwhite', 'gold', 'goldenrod', 'gray',
'grey', 'green', 'greenyellow', 'honeydew', 'hotpink',
'indianred', 'indigo', 'ivory', 'khaki', 'lavender',
'lavenderblush', 'lawngreen', 'lemonchiffon', 'lightblue',
'lightcoral', 'lightcyan', 'lightgoldenrodyellow',
'lightgray', 'lightgrey', 'lightgreen', 'lightpink',
'lightsalmon', 'lightseagreen', 'lightskyblue',
'lightslategray', 'lightslategrey', 'lightsteelblue',
'lightyellow', 'lime', 'limegreen', 'linen', 'magenta',
'maroon', 'mediumaquamarine', 'mediumblue', 'mediumorchid',
'mediumpurple', 'mediumseagreen', 'mediumslateblue',
'mediumspringgreen', 'mediumturquoise', 'mediumvioletred',
'midnightblue', 'mintcream', 'mistyrose', 'moccasin',
'navajowhite', 'navy', 'oldlace', 'olive', 'olivedrab',
'orange', 'orangered', 'orchid', 'palegoldenrod', 'palegreen',
'paleturquoise', 'palevioletred', 'papayawhip', 'peachpuff',
'peru', 'pink', 'plum', 'powderblue', 'purple', 'red',
'rosybrown', 'royalblue', 'saddlebrown', 'salmon',
'sandybrown', 'seagreen', 'seashell', 'sienna', 'silver',
'skyblue', 'slateblue', 'slategray', 'slategrey', 'snow',
'springgreen', 'steelblue', 'tan', 'teal', 'thistle',
'tomato', 'turquoise', 'violet', 'wheat', 'white',
'whitesmoke', 'yellow', 'yellowgreen']
__slots__ = ['allow_named']
_slot_defaults = _dict_update(Parameter._slot_defaults, allow_named=True)
@typing.overload
def __init__(
self,
default=None, *, allow_named=True,
allow_None=False, doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, allow_named=Undefined, **kwargs):
super().__init__(default=default, **kwargs)
self.allow_named = allow_named
self._validate(self.default)
def _validate(self, val):
self._validate_value(val, self.allow_None)
self._validate_allow_named(val, self.allow_named)
def _validate_value(self, val, allow_None):
if (allow_None and val is None):
return
if not isinstance(val, str):
raise ValueError(
f"{_validate_error_prefix(self)} expects a string value, "
f"not an object of {type(val)}."
)
def _validate_allow_named(self, val, allow_named):
if (val is None and self.allow_None):
return
is_hex = re.match('^#?(([0-9a-fA-F]{2}){3}|([0-9a-fA-F]){3})$', val)
if self.allow_named:
if not is_hex and val.lower() not in self._named_colors:
raise ValueError(
f"{_validate_error_prefix(self)} only takes RGB hex codes "
f"or named colors, received '{val}'."
)
elif not is_hex:
raise ValueError(
f"{_validate_error_prefix(self)} only accepts valid RGB hex "
f"codes, received {val!r}."
)
#-----------------------------------------------------------------------------
# Bytes
#-----------------------------------------------------------------------------
class Bytes(Parameter):
"""
A Bytes Parameter, with a default value and optional regular
expression (regex) matching.
Similar to the String parameter, but instead of type string
this parameter only allows objects of type bytes (e.g. b'bytes').
"""
__slots__ = ['regex']
_slot_defaults = _dict_update(
Parameter._slot_defaults, default=b"", regex=None, allow_None=False,
)
@typing.overload
def __init__(
self,
default=b"", *, regex=None, allow_None=False,
doc=None, label=None, precedence=None, instantiate=False,
constant=False, readonly=False, pickle_default_value=True, per_instance=True,
allow_refs=False, nested_refs=False
):
...
@_deprecate_positional_args
def __init__(self, default=Undefined, *, regex=Undefined, allow_None=Undefined, **kwargs):
super().__init__(default=default, **kwargs)
self.regex = regex
self._validate(self.default)
def _validate_regex(self, val, regex):
if (val is None and self.allow_None):
return
if regex is not None and re.match(regex, val) is None:
raise ValueError(
f"{_validate_error_prefix(self)} value {val!r} "
f"does not match regex {regex!r}."
)
def _validate_value(self, val, allow_None):
if allow_None and val is None:
return
if not isinstance(val, bytes):
raise ValueError(
f"{_validate_error_prefix(self)} only takes a byte string value, "
f"not value of {type(val)}."
)
def _validate(self, val):
self._validate_value(val, self.allow_None)
self._validate_regex(val, self.regex)
param-2.1.1/param/reactive.py 0000664 0000000 0000000 00000131511 14636363363 0016106 0 ustar 00root root 0000000 0000000 """
reactive API
`rx` is a wrapper around a Python object that lets users create
reactive expression pipelines by calling existing APIs on an object with dynamic
parameters or widgets.
An `rx` instance watches what operations are applied to the object
and records these on each instance, which are then strung together
into a chain.
The original input to an `rx` object is stored in a mutable list and can be
accessed via the `_obj` property. The shared mutable data structure
ensures that all `rx` instances created from the same object can
hold a shared reference that can be updated, e.g. via the `.value`
property or because the input was itself a reference to some object that
can potentially be updated.
When an operation is applied to an `rx` instance, it will
record the operation and create a new instance using the `_clone` method,
e.g. `dfi.head()` first records that the `'head'` attribute is
accessed, which is achieved by overriding `__getattribute__`. A new
reactive object is returned, which will then record that it is
being called, and that new object will be itself called, as
`rx` implements `__call__`. `__call__` returns another
`rx` instance. To be able to watch all the potential
operations that may be applied to an object, `rx` implements:
- `__getattribute__`: Watching for attribute accesses
- `__call__`: Intercepting both actual calls or method calls if an
attribute was previously accessed
- `__getitem__`: Intercepting indexing operations
- Operators: Implementing all valid operators `__gt__`, `__add__`, etc.
- `__array_ufunc__`: Intercepting numpy universal function calls
The `rx` object evaluates operations lazily, but whenever the
current value is needed the operations are automatically
evaluated. Note that even attribute access or tab-completion
operations can result in evaluation of the pipeline. This is very
useful in a REPL, as this allows inspecting the transformed
object at any point of the pipeline, and as such provide correct
auto-completion and docstrings. E.g. executing `dfi.A.max?` in an
interactive REPL or notebook where it allows returning the docstring
of the method being accessed.
The actual operations are stored as a dictionary on the `_operation`
attribute of each instance. They contain 4 keys:
- `fn`: The function to apply (either an actual function or a string
indicating the operation is a method on the object)
- `args`: Any arguments to supply to the `fn`.
- `kwargs`: Any keyword arguments to supply to the `fn`.
- `reverse`: If the function is not a method this indicates whether
the first arg and the input object should be supplied in
reverse order.
The `_depth` attribute starts at 0 and is incremented by 1 every time
a new `rx` instance is created part of a chain. The root
instance in a reactive expression has a `_depth` of 0. A reactive
expression can consist of multiple chains, such as `dfi[dfi.A > 1]`,
as the `rx` instance is referenced twice in the expression. As a
consequence `_depth` is not the total count of `rx` instance
creations of a pipeline, it is the count of instances created in the
outer chain. In the example, that would be `dfi[]`. Each `rx`
instance keeps a reference to the previous instance in the chain and
each instance tracks whether its current value is up-to-date via the
`_dirty` attribute, which is set to False if any dependency changes.
The `_method` attribute is a string that temporarily stores the
method/attr accessed on the object, e.g. `_method` is 'head' in
`dfi.head()`, until the `rx` instance created in the pipeline
is called at which point `_method` is reset to None. In cases such as
`dfi.head` or `dfi.A`, `_method` is not (yet) reset to None. At this
stage the `rx` instance returned has its `_current` attribute
not updated, e.g. `dfi.A._current` is still the original dataframe,
not the 'A' series. Keeping `_method` is thus useful for instance to
display `dfi.A`, as the evaluation of the object will check whether
`_method` is set or not, and if it's set it will use it to compute the
object returned, e.g. the series `df.A` or the method `df.head`, and
display its repr.
"""
from __future__ import annotations
import asyncio
import inspect
import math
import operator
from collections.abc import Iterable, Iterator
from functools import partial
from types import FunctionType, MethodType
from typing import Any, Callable, Optional
from .depends import depends
from .display import _display_accessors, _reactive_display_objs
from .parameterized import (
Parameter, Parameterized, Skip, Undefined, eval_function_with_deps, get_method_owner,
register_reference_transform, resolve_ref, resolve_value, transform_reference
)
from .parameters import Boolean, Event
from ._utils import _to_async_gen, iscoroutinefunction, full_groupby
class Wrapper(Parameterized):
"""
Helper class to allow updating literal values easily.
"""
object = Parameter(allow_refs=False)
class GenWrapper(Parameterized):
"""
Helper class to allow streaming from generator functions.
"""
object = Parameter(allow_refs=True)
class Trigger(Parameterized):
"""
Helper class to allow triggering an event under some condition.
"""
value = Event()
def __init__(self, parameters=None, internal=False, **params):
super().__init__(**params)
self.internal = internal
self.parameters = parameters
class Resolver(Parameterized):
"""
Helper class to allow (recursively) resolving references.
"""
object = Parameter(allow_refs=True)
recursive = Boolean(default=False)
value = Parameter()
def __init__(self, **params):
self._watchers = []
super().__init__(**params)
def _resolve_value(self, *events):
nested = self.param.object.nested_refs
refs = resolve_ref(self.object, nested)
value = resolve_value(self.object, nested)
if self.recursive:
new_refs = [r for r in resolve_ref(value, nested) if r not in refs]
while new_refs:
refs += new_refs
value = resolve_value(value, nested)
new_refs = [r for r in resolve_ref(value, nested) if r not in refs]
if events:
self._update_refs(refs)
self.value = value
return refs
@depends('object', watch=True, on_init=True)
def _resolve_object(self):
refs = self._resolve_value()
self._update_refs(refs)
def _update_refs(self, refs):
for w in self._watchers:
(w.inst or w.cls).param.unwatch(w)
self._watchers = []
for _, params in full_groupby(refs, lambda x: id(x.owner)):
self._watchers.append(
params[0].owner.param.watch(self._resolve_value, [p.name for p in params])
)
class NestedResolver(Resolver):
object = Parameter(allow_refs=True, nested_refs=True)
class reactive_ops:
"""
Namespace for reactive operators.
Implements operators that cannot be implemented using regular
Python syntax.
"""
def __init__(self, reactive):
self._reactive = reactive
def _as_rx(self):
return self._reactive if isinstance(self._reactive, rx) else self()
def __call__(self):
rxi = self._reactive
return rxi if isinstance(rx, rx) else rx(rxi)
def and_(self, other):
"""
Replacement for the ``and`` statement.
"""
return self._as_rx()._apply_operator(lambda obj, other: obj and other, other)
def bool(self):
"""
__bool__ cannot be implemented so it is provided as a method.
"""
return self._as_rx()._apply_operator(bool)
def buffer(self, n):
"""
Collects the last n items that were emitted.
"""
items = []
def collect(new, n):
items.append(new)
while len(items) > n:
items.pop(0)
return items
return self._as_rx()._apply_operator(collect, n)
def in_(self, other):
"""
Replacement for the ``in`` statement.
"""
return self._as_rx()._apply_operator(operator.contains, other, reverse=True)
def is_(self, other):
"""
Replacement for the ``is`` statement.
"""
return self._as_rx()._apply_operator(operator.is_, other)
def is_not(self, other):
"""
Replacement for the ``is not`` statement.
"""
return self._as_rx()._apply_operator(operator.is_not, other)
def len(self):
"""
__len__ cannot be implemented so it is provided as a method.
"""
return self._as_rx()._apply_operator(len)
def map(self, func, /, *args, **kwargs):
"""
Apply a function to each item.
Arguments
---------
func: function
Function to apply.
args: iterable, optional
Positional arguments to pass to `func`.
kwargs: mapping, optional
A dictionary of keywords to pass to `func`.
"""
if inspect.isasyncgenfunction(func) or inspect.isgeneratorfunction(func):
raise TypeError(
"Cannot map a generator function. Only regular function "
"or coroutine functions are permitted."
)
if inspect.iscoroutinefunction(func):
async def apply(vs, *args, **kwargs):
return list(await asyncio.gather(*(func(v, *args, **kwargs) for v in vs)))
else:
def apply(vs, *args, **kwargs):
return [func(v, *args, **kwargs) for v in vs]
return self._as_rx()._apply_operator(apply, *args, **kwargs)
def not_(self):
"""
__bool__ cannot be implemented so not has to be provided as a method.
"""
return self._as_rx()._apply_operator(operator.not_)
def or_(self, other):
"""
Replacement for the ``or`` statement.
"""
return self._as_rx()._apply_operator(lambda obj, other: obj or other, other)
def pipe(self, func, /, *args, **kwargs):
"""
Apply chainable functions.
Arguments
---------
func: function
Function to apply.
args: iterable, optional
Positional arguments to pass to `func`.
kwargs: mapping, optional
A dictionary of keywords to pass to `func`.
"""
return self._as_rx()._apply_operator(func, *args, **kwargs)
def resolve(self, nested=True, recursive=False):
"""
Resolves references held by the expression.
As an example if the expression returns a list of parameters
this operation will return a list of the parameter values.
Arguments
---------
nested: bool
Whether to resolve references contained within nested objects,
i.e. tuples, lists, sets and dictionaries.
recursive: bool
Whether to recursively resolve references, i.e. if a reference
itself returns a reference we recurse into it until no more
references can be resolved.
"""
resolver_type = NestedResolver if nested else Resolver
resolver = resolver_type(object=self._reactive, recursive=recursive)
return resolver.param.value.rx()
def updating(self):
"""
Returns a new expression that is True while the expression is updating.
"""
wrapper = Wrapper(object=False)
self._watch(lambda e: wrapper.param.update(object=True), precedence=-999)
self._watch(lambda e: wrapper.param.update(object=False), precedence=999)
return wrapper.param.object.rx()
def when(self, *dependencies, initial=Undefined):
"""
Returns a reactive expression that emits the contents of this
expression only when the dependencies change. If initial value
is provided and the dependencies are all param.Event types the
expression will not be evaluated until the first event is
triggered.
Arguments
---------
dependencies: param.Parameter | rx
A dependency that will trigger an update in the output.
initial: object
Object that will stand in for the actual value until the
first time a param.Event in the dependencies is triggered.
"""
deps = [p for d in dependencies for p in resolve_ref(d)]
is_event = all(isinstance(dep, Event) for dep in deps)
def eval(*_, evaluated=[]):
if is_event and initial is not Undefined and not evaluated:
# Abuse mutable default value to keep track of evaluation state
evaluated.append(True)
return initial
else:
return self.value
return bind(eval, *deps).rx()
def where(self, x, y):
"""
Returns either x or y depending on the current state of the
expression, i.e. replaces a ternary if statement.
Arguments
---------
x: object
The value to return if the expression evaluates to True.
y: object
The value to return if the expression evaluates to False.
"""
xrefs = resolve_ref(x)
yrefs = resolve_ref(y)
if isinstance(self._reactive, rx):
params = self._reactive._params
else:
params = resolve_ref(self._reactive)
trigger = Trigger(parameters=params)
if xrefs:
def trigger_x(*args):
if self.value:
trigger.param.trigger('value')
bind(trigger_x, *xrefs, watch=True)
if yrefs:
def trigger_y(*args):
if not self.value:
trigger.param.trigger('value')
bind(trigger_y, *yrefs, watch=True)
def ternary(condition, _):
return resolve_value(x) if condition else resolve_value(y)
return bind(ternary, self._reactive, trigger.param.value)
# Operations to get the output and set the input of an expression
@property
def value(self):
"""
Returns the current state of the reactive expression by
evaluating the pipeline.
"""
if isinstance(self._reactive, rx):
return self._reactive._resolve()
elif isinstance(self._reactive, Parameter):
return getattr(self._reactive.owner, self._reactive.name)
else:
return self._reactive()
@value.setter
def value(self, new):
"""
Allows overriding the original input to the pipeline.
"""
if isinstance(self._reactive, Parameter):
raise AttributeError(
"`Parameter.rx.value = value` is not supported. Cannot override "
"parameter value."
)
elif not isinstance(self._reactive, rx):
raise AttributeError(
"`bind(...).rx.value = value` is not supported. Cannot override "
"the output of a function."
)
elif self._reactive._root is not self._reactive:
raise AttributeError(
"The value of a derived expression cannot be set. Ensure you "
"set the value on the root node wrapping a concrete value, e.g.:"
"\n\n a = rx(1)\n b = a + 1\n a.rx.value = 2\n\n "
"is valid but you may not set `b.rx.value = 2`."
)
if self._reactive._wrapper is None:
raise AttributeError(
"Setting the value of a reactive expression is only "
"supported if it wraps a concrete value. A reactive "
"expression wrapping a Parameter or another dynamic "
"reference cannot be updated."
)
self._reactive._wrapper.object = resolve_value(new)
def watch(self, fn=None, onlychanged=True, queued=False, precedence=0):
"""
Adds a callable that observes the output of the pipeline.
If no callable is provided this simply causes the expression
to be eagerly evaluated.
"""
if precedence < 0:
raise ValueError("User-defined watch callbacks must declare "
"a positive precedence. Negative precedences "
"are reserved for internal Watchers.")
self._watch(fn, onlychanged=onlychanged, queued=queued, precedence=precedence)
def _watch(self, fn=None, onlychanged=True, queued=False, precedence=0):
def cb(value):
from .parameterized import async_executor
if iscoroutinefunction(fn):
async_executor(partial(fn, value))
elif fn is not None:
fn(value)
bind(cb, self._reactive, watch=True)
def bind(function, *args, watch=False, **kwargs):
"""
Given a function, returns a wrapper function that binds the values
of some or all arguments to Parameter values and expresses Param
dependencies on those values, so that the function can be invoked
whenever the underlying values change and the output will reflect
those updated values.
As for functools.partial, arguments can also be bound to constants,
which allows all of the arguments to be bound, leaving a simple
callable object.
Arguments
---------
function: callable
The function to bind constant or dynamic args and kwargs to.
args: object, param.Parameter
Positional arguments to bind to the function.
watch: boolean
Whether to evaluate the function automatically whenever one of
the bound parameters changes.
kwargs: object, param.Parameter
Keyword arguments to bind to the function.
Returns
-------
Returns a new function with the args and kwargs bound to it and
annotated with all dependencies.
"""
args, kwargs = (
tuple(transform_reference(arg) for arg in args),
{key: transform_reference(arg) for key, arg in kwargs.items()}
)
dependencies = {}
# If the wrapped function has a dependency add it
fn_dep = transform_reference(function)
if isinstance(fn_dep, Parameter) or hasattr(fn_dep, '_dinfo'):
dependencies['__fn'] = fn_dep
# Extract dependencies from args and kwargs
for i, p in enumerate(args):
if hasattr(p, '_dinfo'):
for j, arg in enumerate(p._dinfo['dependencies']):
dependencies[f'__arg{i}_arg{j}'] = arg
for kw, kwarg in p._dinfo['kw'].items():
dependencies[f'__arg{i}_arg_{kw}'] = kwarg
elif isinstance(p, Parameter):
dependencies[f'__arg{i}'] = p
for kw, v in kwargs.items():
if hasattr(v, '_dinfo'):
for j, arg in enumerate(v._dinfo['dependencies']):
dependencies[f'__kwarg_{kw}_arg{j}'] = arg
for pkw, kwarg in v._dinfo['kw'].items():
dependencies[f'__kwarg_{kw}_{pkw}'] = kwarg
elif isinstance(v, Parameter):
dependencies[kw] = v
def combine_arguments(wargs, wkwargs, asynchronous=False):
combined_args = []
for arg in args:
if hasattr(arg, '_dinfo'):
arg = eval_function_with_deps(arg)
elif isinstance(arg, Parameter):
arg = getattr(arg.owner, arg.name)
combined_args.append(arg)
combined_args += list(wargs)
combined_kwargs = {}
for kw, arg in kwargs.items():
if hasattr(arg, '_dinfo'):
arg = eval_function_with_deps(arg)
elif isinstance(arg, Parameter):
arg = getattr(arg.owner, arg.name)
combined_kwargs[kw] = arg
for kw, arg in wkwargs.items():
if asynchronous:
if kw.startswith('__arg'):
index = kw[5:]
if index.isdigit():
combined_args[int(index)] = arg
elif kw.startswith('__kwarg'):
substring = kw[8:]
if substring in combined_kwargs:
combined_kwargs[substring] = arg
continue
elif kw.startswith('__arg') or kw.startswith('__kwarg') or kw.startswith('__fn'):
continue
combined_kwargs[kw] = arg
return combined_args, combined_kwargs
def eval_fn():
if callable(function):
fn = function
else:
p = transform_reference(function)
if isinstance(p, Parameter):
fn = getattr(p.owner, p.name)
else:
fn = eval_function_with_deps(p)
return fn
if inspect.isgeneratorfunction(function):
def wrapped(*wargs, **wkwargs):
combined_args, combined_kwargs = combine_arguments(
wargs, wkwargs, asynchronous=True
)
evaled = eval_fn()(*combined_args, **combined_kwargs)
for val in evaled:
yield val
wrapper_fn = depends(**dependencies, watch=watch)(wrapped)
wrapped._dinfo = wrapper_fn._dinfo
elif inspect.isasyncgenfunction(function):
async def wrapped(*wargs, **wkwargs):
combined_args, combined_kwargs = combine_arguments(
wargs, wkwargs, asynchronous=True
)
evaled = eval_fn()(*combined_args, **combined_kwargs)
async for val in evaled:
yield val
wrapper_fn = depends(**dependencies, watch=watch)(wrapped)
wrapped._dinfo = wrapper_fn._dinfo
elif iscoroutinefunction(function):
@depends(**dependencies, watch=watch)
async def wrapped(*wargs, **wkwargs):
combined_args, combined_kwargs = combine_arguments(
wargs, wkwargs, asynchronous=True
)
evaled = eval_fn()(*combined_args, **combined_kwargs)
return await evaled
else:
@depends(**dependencies, watch=watch)
def wrapped(*wargs, **wkwargs):
combined_args, combined_kwargs = combine_arguments(wargs, wkwargs)
return eval_fn()(*combined_args, **combined_kwargs)
wrapped.__bound_function__ = function
wrapped.rx = reactive_ops(wrapped)
_reactive_display_objs.add(wrapped)
for name, accessor in _display_accessors.items():
setattr(wrapped, name, accessor(wrapped))
return wrapped
class rx:
"""
`rx` allows wrapping objects and then operating on them
interactively while recording any operations applied to them. By
recording all arguments or operands in the operations the recorded
pipeline can be replayed if an operand represents a dynamic value.
Parameters
----------
obj: any
A supported data structure object
Examples
--------
Instantiate it from an object:
>>> ifloat = rx(3.14)
>>> ifloat * 2
6.28
Then update the original value and see the new result:
>>> ifloat.value = 1
2
"""
_accessors: dict[str, Callable[[rx], Any]] = {}
_display_options: tuple[str] = ()
_display_handlers: dict[type, tuple[Any, dict[str, Any]]] = {}
_method_handlers: dict[str, Callable] = {}
@classmethod
def register_accessor(
cls, name: str, accessor: Callable[[rx], Any],
predicate: Optional[Callable[[Any], bool]] = None
):
"""
Registers an accessor that extends rx with custom behavior.
Arguments
---------
name: str
The name of the accessor will be attribute-accessible under.
accessor: Callable[[rx], any]
A callable that will return the accessor namespace object
given the rx object it is registered on.
predicate: Callable[[Any], bool] | None
"""
cls._accessors[name] = (accessor, predicate)
@classmethod
def register_display_handler(cls, obj_type, handler, **kwargs):
"""
Registers a display handler for a specific type of object,
making it possible to define custom display options for
specific objects.
Arguments
---------
obj_type: type | callable
The type to register a custom display handler on.
handler: Viewable | callable
A Viewable or callable that is given the object to be displayed
and the custom keyword arguments.
kwargs: dict[str, Any]
Additional display options to register for this type.
"""
cls._display_handlers[obj_type] = (handler, kwargs)
@classmethod
def register_method_handler(cls, method, handler):
"""
Registers a handler that is called when a specific method on
an object is called.
"""
cls._method_handlers[method] = handler
def __new__(cls, obj=None, **kwargs):
wrapper = None
obj = transform_reference(obj)
if kwargs.get('fn'):
# rx._clone codepath
fn = kwargs.pop('fn')
wrapper = kwargs.pop('_wrapper', None)
elif inspect.isgeneratorfunction(obj) or iscoroutinefunction(obj):
# Resolves generator and coroutine functions lazily
wrapper = GenWrapper(object=obj)
fn = bind(lambda obj: obj, wrapper.param.object)
obj = Undefined
elif isinstance(obj, (FunctionType, MethodType)) and hasattr(obj, '_dinfo'):
# Bound functions and methods are resolved on access
fn = obj
obj = None
elif isinstance(obj, Parameter):
fn = bind(lambda obj: obj, obj)
obj = getattr(obj.owner, obj.name)
else:
# For all other objects wrap them so they can be updated
# via .rx.value property
wrapper = Wrapper(object=obj)
fn = bind(lambda obj: obj, wrapper.param.object)
inst = super(rx, cls).__new__(cls)
inst._fn = fn
inst._shared_obj = kwargs.get('_shared_obj', None if obj is None else [obj])
inst._wrapper = wrapper
return inst
def __init__(
self, obj=None, operation=None, fn=None, depth=0, method=None, prev=None,
_shared_obj=None, _current=None, _wrapper=None, **kwargs
):
# _init is used to prevent to __getattribute__ to execute its
# specialized code.
self._init = False
display_opts = {}
for _, opts in self._display_handlers.values():
for k, o in opts.items():
display_opts[k] = o
display_opts.update({
dopt: kwargs.pop(dopt) for dopt in self._display_options + tuple(display_opts)
if dopt in kwargs
})
self._display_opts = display_opts
self._method = method
self._operation = operation
self._depth = depth
self._dirty = _current is None
self._dirty_obj = False
self._current_task = None
self._error_state = None
self._current_ = _current
if isinstance(obj, rx) and not prev:
self._prev = obj
else:
self._prev = prev
# Define special trigger parameter if operation has to be lazily evaluated
if operation and (iscoroutinefunction(operation['fn']) or inspect.isgeneratorfunction(operation['fn'])):
self._trigger = Trigger(internal=True)
self._current_ = Undefined
else:
self._trigger = None
self._root = self._compute_root()
self._fn_params = self._compute_fn_params()
self._internal_params = self._compute_params()
# Filter params that external objects depend on, ensuring
# that Trigger parameters do not cause double execution
self._params = [
p for p in self._internal_params if (not isinstance(p.owner, Trigger) or p.owner.internal)
or any (p not in self._internal_params for p in p.owner.parameters)
]
self._setup_invalidations(depth)
self._kwargs = kwargs
self.rx = reactive_ops(self)
self._init = True
for name, accessor in _display_accessors.items():
setattr(self, name, accessor(self))
for name, (accessor, predicate) in rx._accessors.items():
if predicate is None or predicate(self._current):
setattr(self, name, accessor(self))
@property
def _obj(self):
if self._shared_obj is None:
self._obj = eval_function_with_deps(self._fn)
elif self._root._dirty_obj:
root = self._root
root._shared_obj[0] = eval_function_with_deps(root._fn)
root._dirty_obj = False
return self._shared_obj[0]
@_obj.setter
def _obj(self, obj):
if self._shared_obj is None:
self._shared_obj = [obj]
else:
self._shared_obj[0] = obj
@property
def _current(self):
if self._error_state:
raise self._error_state
elif self._dirty or self._root._dirty_obj:
self._resolve()
return self._current_
def _compute_root(self):
if self._prev is None:
return self
root = self
while root._prev is not None:
root = root._prev
return root
def _compute_fn_params(self) -> list[Parameter]:
if self._fn is None:
return []
owner = get_method_owner(self._fn)
if owner is not None:
deps = [
dep.pobj for dep in owner.param.method_dependencies(self._fn.__name__)
]
return deps
dinfo = getattr(self._fn, '_dinfo', {})
args = list(dinfo.get('dependencies', []))
kwargs = list(dinfo.get('kw', {}).values())
return args + kwargs
def _compute_params(self) -> list[Parameter]:
ps = list(self._fn_params)
if self._trigger:
ps.append(self._trigger.param.value)
# Collect parameters on previous objects in chain
prev = self._prev
while prev is not None:
for p in prev._params:
if p not in ps:
ps.append(p)
prev = prev._prev
if self._operation is None:
return ps
# Accumulate dependencies in args and/or kwargs
for ref in resolve_ref(self._operation['fn']):
if ref not in ps:
ps.append(ref)
for arg in list(self._operation['args'])+list(self._operation['kwargs'].values()):
for ref in resolve_ref(arg, recursive=True):
if ref not in ps:
ps.append(ref)
return ps
def _setup_invalidations(self, depth: int = 0):
"""
Since the parameters of the pipeline can change at any time
we have to invalidate the internal state of the pipeline.
To handle both invalidations of the inputs of the pipeline
and the pipeline itself we set up watchers on both.
1. The first invalidation we have to set up is to re-evaluate
the function that feeds the pipeline. Only the root node of
a pipeline has to perform this invalidation because all
leaf nodes inherit the same shared_obj. This avoids
evaluating the same function for every branch of the pipeline.
2. The second invalidation is for the pipeline itself, i.e.
if any parameter changes we have to notify the pipeline that
it has to re-evaluate the pipeline. This is done by marking
the pipeline as `_dirty`. The next time the `_current` value
is requested the value is resolved by re-executing the
pipeline.
"""
if self._fn is not None:
for _, params in full_groupby(self._fn_params, lambda x: id(x.owner)):
fps = [p.name for p in params if p in self._root._fn_params]
if fps:
params[0].owner.param._watch(self._invalidate_obj, fps, precedence=-1)
for _, params in full_groupby(self._internal_params, lambda x: id(x.owner)):
params[0].owner.param._watch(self._invalidate_current, [p.name for p in params], precedence=-1)
def _invalidate_current(self, *events):
if all(event.obj is self._trigger for event in events):
return
self._dirty = True
self._error_state = None
def _invalidate_obj(self, *events):
self._root._dirty_obj = True
self._error_state = None
async def _resolve_async(self, obj):
self._current_task = task = asyncio.current_task()
if inspect.isasyncgen(obj):
async for val in obj:
if self._current_task is not task:
break
self._current_ = val
self._trigger.param.trigger('value')
else:
value = await obj
if self._current_task is task:
self._current_ = value
self._trigger.param.trigger('value')
def _lazy_resolve(self, obj):
from .parameterized import async_executor
if inspect.isgenerator(obj):
obj = _to_async_gen(obj)
async_executor(partial(self._resolve_async, obj))
def _resolve(self):
if self._error_state:
raise self._error_state
elif self._dirty or self._root._dirty_obj:
try:
obj = self._obj if self._prev is None else self._prev._resolve()
if obj is Skip or obj is Undefined:
self._current_ = Undefined
raise Skip
operation = self._operation
if operation:
obj = self._eval_operation(obj, operation)
if inspect.isasyncgen(obj) or inspect.iscoroutine(obj) or inspect.isgenerator(obj):
self._lazy_resolve(obj)
obj = Skip
if obj is Skip:
raise Skip
except Skip:
self._dirty = False
return self._current_
except Exception as e:
self._error_state = e
raise e
self._current_ = current = obj
else:
current = self._current_
self._dirty = False
if self._method:
# E.g. `pi = dfi.A` leads to `pi._method` equal to `'A'`.
current = getattr(current, self._method, current)
if hasattr(current, '__call__'):
self.__call__.__func__.__doc__ = self.__call__.__doc__
return current
def _transform_output(self, obj):
"""
Applies custom display handlers before their output.
"""
applies = False
for predicate, (handler, opts) in self._display_handlers.items():
display_opts = {
k: v for k, v in self._display_opts.items() if k in opts
}
display_opts.update(self._kwargs)
try:
applies = predicate(obj, **display_opts)
except TypeError:
applies = predicate(obj)
if applies:
new = handler(obj, **display_opts)
if new is not obj:
return new
return obj
@property
def _callback(self):
params = self._params
def evaluate(*args, **kwargs):
out = self._current
if self._method:
out = getattr(out, self._method)
return self._transform_output(out)
if params:
return bind(evaluate, *params)
return evaluate
def _clone(self, operation=None, copy=False, **kwargs):
operation = operation or self._operation
depth = self._depth + 1
if copy:
kwargs = dict(
self._kwargs, _current=self._current, method=self._method,
prev=self._prev, **kwargs
)
else:
kwargs = dict(prev=self, **dict(self._kwargs, **kwargs))
kwargs = dict(self._display_opts, **kwargs)
return type(self)(
self._obj, operation=operation, depth=depth, fn=self._fn,
_shared_obj=self._shared_obj, _wrapper=self._wrapper,
**kwargs
)
def __dir__(self):
current = self._current
if self._method:
current = getattr(current, self._method)
extras = {attr for attr in dir(current) if not attr.startswith('_')}
try:
return sorted(set(super().__dir__()) | extras)
except Exception:
return sorted(set(dir(type(self))) | set(self.__dict__) | extras)
def _resolve_accessor(self):
if not self._method:
# No method is yet set, as in `dfi.A`, so return a copied clone.
return self._clone(copy=True)
# This is executed when one runs e.g. `dfi.A > 1`, in which case after
# dfi.A the _method 'A' is set (in __getattribute__) which allows
# _resolve_accessor to record the attribute access as an operation.
operation = {
'fn': getattr,
'args': (self._method,),
'kwargs': {},
'reverse': False
}
self._method = None
return self._clone(operation)
def __getattribute__(self, name):
self_dict = super().__getattribute__('__dict__')
if not self_dict.get('_init') or name == 'rx' or name.startswith('_'):
return super().__getattribute__(name)
current = self_dict['_current_']
dirty = self_dict['_dirty']
if dirty:
self._resolve()
current = self_dict['_current_']
method = self_dict['_method']
if method:
current = getattr(current, method)
# Getting all the public attributes available on the current object,
# e.g. `sum`, `head`, etc.
extras = [d for d in dir(current) if not d.startswith('_')]
if (name in extras or current is Undefined) and name not in super().__dir__():
new = self._resolve_accessor()
# Setting the method name for a potential use later by e.g. an
# operator or method, as in `dfi.A > 2`. or `dfi.A.max()`
new._method = name
try:
new.__doc__ = getattr(current, name).__doc__
except Exception:
pass
return new
return super().__getattribute__(name)
def __call__(self, *args, **kwargs):
new = self._clone(copy=True)
method = new._method or '__call__'
if method == '__call__' and self._depth == 0 and not hasattr(self._current, '__call__'):
return self.set_display(*args, **kwargs)
if method in rx._method_handlers:
handler = rx._method_handlers[method]
method = handler(self)
new._method = None
kwargs = dict(kwargs)
operation = {
'fn': method,
'args': args,
'kwargs': kwargs,
'reverse': False
}
return new._clone(operation)
#----------------------------------------------------------------
# rx pipeline APIs
#----------------------------------------------------------------
def __array_ufunc__(self, ufunc, method, *args, **kwargs):
new = self._resolve_accessor()
operation = {
'fn': getattr(ufunc, method),
'args': args[1:],
'kwargs': kwargs,
'reverse': False
}
return new._clone(operation)
def _apply_operator(self, operator, *args, reverse=False, **kwargs):
new = self._resolve_accessor()
operation = {
'fn': operator,
'args': args,
'kwargs': kwargs,
'reverse': reverse
}
return new._clone(operation)
# Builtin functions
def __abs__(self):
return self._apply_operator(abs)
def __str__(self):
return self._apply_operator(str)
def __round__(self, ndigits=None):
args = () if ndigits is None else (ndigits,)
return self._apply_operator(round, *args)
# Unary operators
def __ceil__(self):
return self._apply_operator(math.ceil)
def __floor__(self):
return self._apply_operator(math.floor)
def __invert__(self):
return self._apply_operator(operator.inv)
def __neg__(self):
return self._apply_operator(operator.neg)
def __pos__(self):
return self._apply_operator(operator.pos)
def __trunc__(self):
return self._apply_operator(math.trunc)
# Binary operators
def __add__(self, other):
return self._apply_operator(operator.add, other)
def __and__(self, other):
return self._apply_operator(operator.and_, other)
def __contains_(self, other):
return self._apply_operator(operator.contains, other)
def __divmod__(self, other):
return self._apply_operator(divmod, other)
def __eq__(self, other):
return self._apply_operator(operator.eq, other)
def __floordiv__(self, other):
return self._apply_operator(operator.floordiv, other)
def __ge__(self, other):
return self._apply_operator(operator.ge, other)
def __gt__(self, other):
return self._apply_operator(operator.gt, other)
def __le__(self, other):
return self._apply_operator(operator.le, other)
def __lt__(self, other):
return self._apply_operator(operator.lt, other)
def __lshift__(self, other):
return self._apply_operator(operator.lshift, other)
def __matmul__(self, other):
return self._apply_operator(operator.matmul, other)
def __mod__(self, other):
return self._apply_operator(operator.mod, other)
def __mul__(self, other):
return self._apply_operator(operator.mul, other)
def __ne__(self, other):
return self._apply_operator(operator.ne, other)
def __or__(self, other):
return self._apply_operator(operator.or_, other)
def __rshift__(self, other):
return self._apply_operator(operator.rshift, other)
def __pow__(self, other):
return self._apply_operator(operator.pow, other)
def __sub__(self, other):
return self._apply_operator(operator.sub, other)
def __truediv__(self, other):
return self._apply_operator(operator.truediv, other)
def __xor__(self, other):
return self._apply_operator(operator.xor, other)
# Reverse binary operators
def __radd__(self, other):
return self._apply_operator(operator.add, other, reverse=True)
def __rand__(self, other):
return self._apply_operator(operator.and_, other, reverse=True)
def __rdiv__(self, other):
return self._apply_operator(operator.div, other, reverse=True)
def __rdivmod__(self, other):
return self._apply_operator(divmod, other, reverse=True)
def __rfloordiv__(self, other):
return self._apply_operator(operator.floordiv, other, reverse=True)
def __rlshift__(self, other):
return self._apply_operator(operator.rlshift, other)
def __rmod__(self, other):
return self._apply_operator(operator.mod, other, reverse=True)
def __rmul__(self, other):
return self._apply_operator(operator.mul, other, reverse=True)
def __ror__(self, other):
return self._apply_operator(operator.or_, other, reverse=True)
def __rpow__(self, other):
return self._apply_operator(operator.pow, other, reverse=True)
def __rrshift__(self, other):
return self._apply_operator(operator.rrshift, other)
def __rsub__(self, other):
return self._apply_operator(operator.sub, other, reverse=True)
def __rtruediv__(self, other):
return self._apply_operator(operator.truediv, other, reverse=True)
def __rxor__(self, other):
return self._apply_operator(operator.xor, other, reverse=True)
def __getitem__(self, other):
return self._apply_operator(operator.getitem, other)
def __iter__(self):
if isinstance(self._current, Iterator):
while True:
try:
new = self._apply_operator(next)
new.rx.value
except RuntimeError:
break
yield new
return
elif not isinstance(self._current, Iterable):
raise TypeError(f'cannot unpack non-iterable {type(self._current).__name__} object.')
items = self._apply_operator(list)
for i in range(len(self._current)):
yield items[i]
def _eval_operation(self, obj, operation):
fn, args, kwargs = operation['fn'], operation['args'], operation['kwargs']
resolved_args = []
for arg in args:
val = resolve_value(arg)
if val is Skip or val is Undefined:
raise Skip
resolved_args.append(val)
resolved_kwargs = {}
for k, arg in kwargs.items():
val = resolve_value(arg)
if val is Skip or val is Undefined:
raise Skip
resolved_kwargs[k] = val
if isinstance(fn, str):
obj = getattr(obj, fn)(*resolved_args, **resolved_kwargs)
elif operation.get('reverse'):
obj = fn(resolved_args[0], obj, *resolved_args[1:], **resolved_kwargs)
else:
obj = fn(obj, *resolved_args, **resolved_kwargs)
return obj
def _rx_transform(obj):
if not isinstance(obj, rx):
return obj
return bind(lambda *_: obj.rx.value, *obj._params)
register_reference_transform(_rx_transform)
param-2.1.1/param/serializer.py 0000664 0000000 0000000 00000026412 14636363363 0016460 0 ustar 00root root 0000000 0000000 """
Classes used to support string serialization of Parameters and
Parameterized objects.
"""
import json
import textwrap
class UnserializableException(Exception):
pass
class UnsafeserializableException(Exception):
pass
def JSONNullable(json_type):
"Express a JSON schema type as nullable to easily support Parameters that allow_None"
return {'anyOf': [ json_type, {'type': 'null'}] }
class Serialization:
"""
Base class used to implement different types of serialization.
"""
@classmethod
def schema(cls, pobj, subset=None):
raise NotImplementedError # noqa: unimplemented method
@classmethod
def serialize_parameters(cls, pobj, subset=None):
"""
Serialize the parameters on a Parameterized object into a
single serialized object, e.g. a JSON string.
"""
raise NotImplementedError # noqa: unimplemented method
@classmethod
def deserialize_parameters(cls, pobj, serialized, subset=None):
"""
Deserialize a serialized object representing one or
more Parameters into a dictionary of parameter values.
"""
raise NotImplementedError # noqa: unimplemented method
@classmethod
def serialize_parameter_value(cls, pobj, pname):
"""
Serialize a single parameter value.
"""
raise NotImplementedError # noqa: unimplemented method
@classmethod
def deserialize_parameter_value(cls, pobj, pname, value):
"""
Deserialize a single parameter value.
"""
raise NotImplementedError # noqa: unimplemented method
class JSONSerialization(Serialization):
"""
Class responsible for specifying JSON serialization, deserialization
and JSON schemas for Parameters and Parameterized classes and
objects.
"""
unserializable_parameter_types = ['Callable']
json_schema_literal_types = {
int:'integer', float:'number', str:'string',
type(None): 'null'
}
@classmethod
def loads(cls, serialized):
return json.loads(serialized)
@classmethod
def dumps(cls, obj):
return json.dumps(obj)
@classmethod
def schema(cls, pobj, safe=False, subset=None):
schema = {}
for name, p in pobj.param.objects('existing').items():
if subset is not None and name not in subset:
continue
schema[name] = p.schema(safe=safe)
if p.doc:
schema[name]['description'] = textwrap.dedent(p.doc).replace('\n', ' ').strip()
if p.label:
schema[name]['title'] = p.label
return schema
@classmethod
def serialize_parameters(cls, pobj, subset=None):
components = {}
for name, p in pobj.param.objects('existing').items():
if subset is not None and name not in subset:
continue
value = pobj.param.get_value_generator(name)
components[name] = p.serialize(value)
return cls.dumps(components)
@classmethod
def deserialize_parameters(cls, pobj, serialization, subset=None):
deserialized = cls.loads(serialization)
components = {}
for name, value in deserialized.items():
if subset is not None and name not in subset:
continue
deserialized = pobj.param[name].deserialize(value)
components[name] = deserialized
return components
# Parameter level methods
@classmethod
def _get_method(cls, ptype, suffix):
"Returns specialized method if available, otherwise None"
method_name = ptype.lower()+'_' + suffix
return getattr(cls, method_name, None)
@classmethod
def param_schema(cls, ptype, p, safe=False, subset=None):
if ptype in cls.unserializable_parameter_types:
raise UnserializableException
dispatch_method = cls._get_method(ptype, 'schema')
if dispatch_method:
schema = dispatch_method(p, safe=safe)
else:
schema = {'type': ptype.lower()}
return JSONNullable(schema) if p.allow_None else schema
@classmethod
def serialize_parameter_value(cls, pobj, pname):
value = pobj.param.get_value_generator(pname)
return cls.dumps(pobj.param[pname].serialize(value))
@classmethod
def deserialize_parameter_value(cls, pobj, pname, value):
value = cls.loads(value)
return pobj.param[pname].deserialize(value)
# Custom Schemas
@classmethod
def class__schema(cls, class_, safe=False):
from .parameterized import Parameterized
if isinstance(class_, tuple):
return {'anyOf': [cls.class__schema(cls_) for cls_ in class_]}
elif class_ in cls.json_schema_literal_types:
return {'type': cls.json_schema_literal_types[class_]}
elif issubclass(class_, Parameterized):
return {'type': 'object', 'properties': class_.param.schema(safe)}
else:
return {'type': 'object'}
@classmethod
def array_schema(cls, p, safe=False):
if safe is True:
msg = ('Array is not guaranteed to be safe for '
'serialization as the dtype is unknown')
raise UnsafeserializableException(msg)
return {'type': 'array'}
@classmethod
def classselector_schema(cls, p, safe=False):
return cls.class__schema(p.class_, safe=safe)
@classmethod
def dict_schema(cls, p, safe=False):
if safe is True:
msg = ('Dict is not guaranteed to be safe for '
'serialization as the key and value types are unknown')
raise UnsafeserializableException(msg)
return {'type': 'object'}
@classmethod
def date_schema(cls, p, safe=False):
return {'type': 'string', 'format': 'date-time'}
@classmethod
def calendardate_schema(cls, p, safe=False):
return {'type': 'string', 'format': 'date'}
@classmethod
def tuple_schema(cls, p, safe=False):
schema = {'type': 'array'}
if p.length is not None:
schema['minItems'] = p.length
schema['maxItems'] = p.length
return schema
@classmethod
def number_schema(cls, p, safe=False):
schema = {'type': p.__class__.__name__.lower() }
return cls.declare_numeric_bounds(schema, p.bounds, p.inclusive_bounds)
@classmethod
def declare_numeric_bounds(cls, schema, bounds, inclusive_bounds):
"Given an applicable numeric schema, augment with bounds information"
if bounds is not None:
(low, high) = bounds
if low is not None:
key = 'minimum' if inclusive_bounds[0] else 'exclusiveMinimum'
schema[key] = low
if high is not None:
key = 'maximum' if inclusive_bounds[1] else 'exclusiveMaximum'
schema[key] = high
return schema
@classmethod
def integer_schema(cls, p, safe=False):
return cls.number_schema(p)
@classmethod
def numerictuple_schema(cls, p, safe=False):
schema = cls.tuple_schema(p, safe=safe)
schema['additionalItems'] = {'type': 'number'}
return schema
@classmethod
def xycoordinates_schema(cls, p, safe=False):
return cls.numerictuple_schema(p, safe=safe)
@classmethod
def range_schema(cls, p, safe=False):
schema = cls.tuple_schema(p, safe=safe)
bounded_number = cls.declare_numeric_bounds(
{'type': 'number'}, p.bounds, p.inclusive_bounds)
schema['additionalItems'] = bounded_number
return schema
@classmethod
def list_schema(cls, p, safe=False):
schema = {'type': 'array'}
if safe is True and p.item_type is None:
msg = ('List without a class specified cannot be guaranteed '
'to be safe for serialization')
raise UnsafeserializableException(msg)
if p.class_ is not None:
schema['items'] = cls.class__schema(p.item_type, safe=safe)
return schema
@classmethod
def objectselector_schema(cls, p, safe=False):
try:
allowed_types = [{'type': cls.json_schema_literal_types[type(obj)]}
for obj in p.objects]
schema = {'anyOf': allowed_types}
schema['enum'] = p.objects
return schema
except:
if safe is True:
msg = ('ObjectSelector cannot be guaranteed to be safe for '
'serialization due to unserializable type in objects')
raise UnsafeserializableException(msg)
return {}
@classmethod
def selector_schema(cls, p, safe=False):
try:
allowed_types = [{'type': cls.json_schema_literal_types[type(obj)]}
for obj in p.objects.values()]
schema = {'anyOf': allowed_types}
schema['enum'] = p.objects
return schema
except:
if safe is True:
msg = ('Selector cannot be guaranteed to be safe for '
'serialization due to unserializable type in objects')
raise UnsafeserializableException(msg)
return {}
@classmethod
def listselector_schema(cls, p, safe=False):
if p.objects is None:
if safe is True:
msg = ('ListSelector cannot be guaranteed to be safe for '
'serialization as allowed objects unspecified')
return {'type': 'array'}
for obj in p.objects:
if type(obj) not in cls.json_schema_literal_types:
msg = 'ListSelector cannot serialize type %s' % type(obj)
raise UnserializableException(msg)
return {'type': 'array', 'items': {'enum': p.objects}}
@classmethod
def dataframe_schema(cls, p, safe=False):
schema = {'type': 'array'}
if safe is True:
msg = ('DataFrame is not guaranteed to be safe for '
'serialization as the column dtypes are unknown')
raise UnsafeserializableException(msg)
if p.columns is None:
schema['items'] = {'type': 'object'}
return schema
mincols, maxcols = None, None
if isinstance(p.columns, int):
mincols, maxcols = p.columns, p.columns
elif isinstance(p.columns, tuple):
mincols, maxcols = p.columns
if isinstance(p.columns, int) or isinstance(p.columns, tuple):
schema['items'] = {'type': 'object', 'minItems': mincols,
'maxItems': maxcols}
if isinstance(p.columns, list) or isinstance(p.columns, set):
literal_types = [{'type':el} for el in cls.json_schema_literal_types.values()]
allowable_types = {'anyOf': literal_types}
properties = {name: allowable_types for name in p.columns}
schema['items'] = {'type': 'object', 'properties': properties}
minrows, maxrows = None, None
if isinstance(p.rows, int):
minrows, maxrows = p.rows, p.rows
elif isinstance(p.rows, tuple):
minrows, maxrows = p.rows
if minrows is not None:
schema['minItems'] = minrows
if maxrows is not None:
schema['maxItems'] = maxrows
return schema
param-2.1.1/param/version.py 0000664 0000000 0000000 00000074601 14636363363 0015777 0 ustar 00root root 0000000 0000000 """
Provide consistent and up-to-date ``__version__`` strings for
Python packages.
See https://github.com/holoviz/autover for more information.
"""
# The Version class is a copy of autover.version.Version v0.2.5,
# except as noted below.
#
# The current version of autover supports a workflow based on tagging
# a git repository, and reports PEP440 compliant version information.
# Previously, the workflow required editing of version numbers in
# source code, and the version was not necessarily PEP440 compliant.
# Version.__new__ is added here to provide the previous Version class
# (OldDeprecatedVersion) if Version is called in the old way.
__author__ = 'Jean-Luc Stevens'
import os, subprocess, json
def run_cmd(args, cwd=None):
kwargs = {}
if os.name == 'nt':
kwargs['creationflags'] = subprocess.CREATE_NO_WINDOW
proc = subprocess.Popen(args, stdout=subprocess.PIPE,
stderr=subprocess.PIPE,
cwd=cwd,
**kwargs)
output, error = (str(s.decode()).strip() for s in proc.communicate())
# Detects errors as _either_ a non-zero return code _or_ messages
# printed to stderr, because the return code is erroneously fixed at
# zero in some cases (see https://github.com/holoviz/param/pull/389).
if proc.returncode != 0 or len(error) > 0:
raise Exception(proc.returncode, error)
return output
class Version:
"""
A simple approach to Python package versioning that supports PyPI
releases and additional information when working with version
control. When obtaining a package from PyPI, the version returned
is a string-formatted rendering of the supplied release tuple.
For instance, release (1,0) tagged as ``v1.0`` in the version
control system will return ``1.0`` for ``str(__version__)``. Any
number of items can be supplied in the release tuple, with either
two or three numeric versioning levels typical.
During development, a command like ``git describe`` will be used to
compute the number of commits since the last version tag, the short
commit hash, and whether the commit is dirty (has changes not yet
committed). Version tags must start with a lowercase 'v' and have a
period in them, e.g. v2.0, v0.9.8 or v0.1 and may include the PEP440
prerelease identifiers of 'a' (alpha) 'b' (beta) or 'rc' (release
candidate) allowing tags such as v2.0.a3, v0.9.8.b3 or v0.1.rc5.
Also note that when version control system (VCS) information is
used, the number of commits since the last version tag is
determined. This approach is often useful in practice to decide
which version is newer for a single developer, but will not
necessarily be reliable when comparing against a different fork or
branch in a distributed VCS.
For git, if you want version control information available even in
an exported archive (e.g. a .zip file from GitHub), you can set
the following line in the .gitattributes file of your project::
__init__.py export-subst
Note that to support pip installation directly from GitHub via git
archive, a .version file must be tracked by the repo to supply the
release number (otherwise only the short SHA is available).
The PEP440 format returned is [N!]N(.N)*[{a|b|rc}N][.postN+SHA]
where everything before .postN is obtained from the tag, the N in
.postN is the number of commits since the last tag and the SHA is
obtained via git describe. This later portion is only shown if the
commit count since the last tag is non zero. Instead of '.post', an
alternate valid prefix such as '.rev', '_rev', '_r' or '.r' may be
supplied."""
def __new__(cls,**kw):
# If called in the old way, provide the previous class. Means
# PEP440/tag based workflow warning below will never appear.
if ('release' in kw and kw['release'] is not None) or \
('dev' in kw and kw['dev'] is not None) or \
('commit_count' in kw):
return OldDeprecatedVersion(**kw)
else:
return super().__new__(cls)
def __init__(self, release=None, fpath=None, commit=None, reponame=None,
commit_count_prefix='.post', archive_commit=None, **kwargs):
"""
:release: Release tuple (corresponding to the current VCS tag)
:commit Short SHA. Set to '$Format:%h$' for git archive support.
:fpath: Set to ``__file__`` to access version control information
:reponame: Used to verify VCS repository name.
"""
self.fpath = fpath
self._expected_commit = commit
if release is not None or 'commit_count' in kwargs:
print('WARNING: param.Version now supports PEP440 and a new tag based workflow. See param/version.py for more details')
self.expected_release = release
self._commit = None if (commit is None or commit.startswith("$Format")) else commit
self._commit_count = None
self._release = None
self._dirty = False
self._prerelease = None
self.archive_commit= archive_commit
self.reponame = reponame
self.commit_count_prefix = commit_count_prefix
@property
def prerelease(self):
"""
Either None or one of 'aN' (alpha), 'bN' (beta) or 'rcN'
(release candidate) where N is an integer.
"""
return self.fetch()._prerelease
@property
def release(self):
"Return the release tuple"
return self.fetch()._release
@property
def commit(self):
"A specification for this particular VCS version, e.g. a short git SHA"
return self.fetch()._commit
@property
def commit_count(self):
"Return the number of commits since the last release"
return self.fetch()._commit_count
@property
def dirty(self):
"True if there are uncommited changes, False otherwise"
return self.fetch()._dirty
def fetch(self):
"""
Returns a tuple of the major version together with the
appropriate SHA and dirty bit (for development version only).
"""
if self._release is not None:
return self
self._release = self.expected_release
if not self.fpath:
self._commit = self._expected_commit
return self
# Only git right now but easily extended to SVN, Mercurial, etc.
for cmd in ['git', 'git.cmd', 'git.exe']:
try:
self.git_fetch(cmd)
break
except OSError:
pass
return self
def git_fetch(self, cmd='git', as_string=False):
commit_argument = self._commit
output = None
try:
if self.reponame is not None:
# Verify this is the correct repository (since fpath could
# be an unrelated git repository, and autover could just have
# been copied/installed into it).
remotes = run_cmd([cmd, 'remote', '-v'],
cwd=os.path.dirname(self.fpath))
repo_matches = ['/' + self.reponame + '.git' ,
# A remote 'server:reponame.git' can also be referred
# to (i.e. cloned) as `server:reponame`.
'/' + self.reponame + ' ']
if not any(m in remotes for m in repo_matches):
try:
output = self._output_from_file()
if output is not None:
self._update_from_vcs(output)
except: pass
if output is None:
# glob pattern (not regexp) matching vX.Y.Z* tags
output = run_cmd([cmd, 'describe', '--long', '--match',
"v[0-9]*.[0-9]*.[0-9]*", '--dirty'],
cwd=os.path.dirname(self.fpath))
if as_string: return output
except Exception as e1:
try:
output = self._output_from_file()
if output is not None:
self._update_from_vcs(output)
if self._known_stale():
self._commit_count = None
if as_string: return output
# If an explicit commit was supplied (e.g from git
# archive), it should take precedence over the file.
if commit_argument:
self._commit = commit_argument
return
except OSError:
if e1.args[1] == 'fatal: No names found, cannot describe anything.':
raise Exception("Cannot find any git version tags of format v*.*")
# If there is any other error, return (release value still useful)
return self
self._update_from_vcs(output)
def _known_stale(self):
"""
The commit is known to be from a file (and therefore stale) if a
SHA is supplied by git archive and doesn't match the parsed commit.
"""
if self._output_from_file() is None:
commit = None
else:
commit = self.commit
known_stale = (self.archive_commit is not None
and not self.archive_commit.startswith('$Format')
and self.archive_commit != commit)
if known_stale: self._commit_count = None
return known_stale
def _output_from_file(self, entry='git_describe'):
"""
Read the version from a .version file that may exist alongside __init__.py.
This file can be generated by piping the following output to file:
git describe --long --match v*.*
"""
try:
vfile = os.path.join(os.path.dirname(self.fpath), '.version')
with open(vfile) as f:
return json.loads(f.read()).get(entry, None)
except: # File may be missing if using pip + git archive
return None
def _update_from_vcs(self, output):
"Update state based on the VCS state e.g the output of git describe"
split = output[1:].split('-')
dot_split = split[0].split('.')
for prefix in ['a','b','rc']:
if prefix in dot_split[-1]:
prefix_split = dot_split[-1].split(prefix)
self._prerelease = prefix + prefix_split[-1]
dot_split[-1] = prefix_split[0]
self._release = tuple(int(el) for el in dot_split)
self._commit_count = int(split[1])
self._commit = str(split[2][1:]) # Strip out 'g' prefix ('g'=>'git')
self._dirty = (split[-1]=='dirty')
return self
def __str__(self):
"""
Version in x.y.z string format. Does not include the "v"
prefix of the VCS version tags, for pip compatibility.
If the commit count is non-zero or the repository is dirty,
the string representation is equivalent to the output of::
git describe --long --match v*.* --dirty
(with "v" prefix removed).
"""
known_stale = self._known_stale()
if self.release is None and not known_stale:
extracted_directory_tag = self._output_from_file(entry='extracted_directory_tag')
return 'None' if extracted_directory_tag is None else extracted_directory_tag
elif self.release is None and known_stale:
extracted_directory_tag = self._output_from_file(entry='extracted_directory_tag')
if extracted_directory_tag is not None:
return extracted_directory_tag
return '0.0.0+g{SHA}-gitarchive'.format(SHA=self.archive_commit)
release = '.'.join(str(el) for el in self.release)
prerelease = '' if self.prerelease is None else self.prerelease
if self.commit_count == 0 and not self.dirty:
return release + prerelease
commit = self.commit
dirty = '-dirty' if self.dirty else ''
archive_commit = ''
if known_stale:
archive_commit = '-gitarchive'
commit = self.archive_commit
if archive_commit != '':
postcount = self.commit_count_prefix + '0'
elif self.commit_count not in [0, None]:
postcount = self.commit_count_prefix + str(self.commit_count)
else:
postcount = ''
components = [release, prerelease, postcount,
'' if commit is None else '+g' + commit, dirty,
archive_commit]
return ''.join(components)
def __repr__(self):
return str(self)
def abbrev(self):
"""
Abbreviated string representation of just the release number.
"""
return '.'.join(str(el) for el in self.release)
def verify(self, string_version=None):
"""
Check that the version information is consistent with the VCS
before doing a release. If supplied with a string version,
this is also checked against the current version. Should be
called from setup.py with the declared package version before
releasing to PyPI.
"""
if string_version and string_version != str(self):
raise Exception("Supplied string version does not match current version.")
if self.dirty:
raise Exception("Current working directory is dirty.")
if self.expected_release is not None and self.release != self.expected_release:
raise Exception("Declared release does not match current release tag.")
if self.commit_count !=0:
raise Exception("Please update the VCS version tag before release.")
if (self._expected_commit is not None
and not self._expected_commit.startswith( "$Format")):
raise Exception("Declared release does not match the VCS version tag")
@classmethod
def get_setup_version(cls, setup_path, reponame, describe=False,
dirty='report', pkgname=None, archive_commit=None):
"""
Helper for use in setup.py to get the version from the .version file (if available)
or more up-to-date information from git describe (if available).
Assumes the __init__.py will be found in the directory
{reponame}/__init__.py relative to setup.py unless pkgname is
explicitly specified in which case that name is used instead.
If describe is True, the raw string obtained from git described is
returned which is useful for updating the .version file.
The dirty policy can be one of 'report', 'strip', 'raise'. If it is
'report' the version string may end in '-dirty' if the repository is
in a dirty state. If the policy is 'strip', the '-dirty' suffix
will be stripped out if present. If the policy is 'raise', an
exception is raised if the repository is in a dirty state. This can
be useful if you want to make sure packages are not built from a
dirty repository state.
"""
pkgname = reponame if pkgname is None else pkgname
policies = ['raise','report', 'strip']
if dirty not in policies:
raise AssertionError("get_setup_version dirty policy must be in %r" % policies)
fpath = os.path.join(setup_path, pkgname, "__init__.py")
version = Version(fpath=fpath, reponame=reponame, archive_commit=archive_commit)
if describe:
vstring = version.git_fetch(as_string=True)
else:
vstring = str(version)
if version.dirty and dirty == 'raise':
raise AssertionError('Repository is in a dirty state.')
elif version.dirty and dirty=='strip':
return vstring.replace('-dirty', '')
else:
return vstring
@classmethod
def extract_directory_tag(cls, setup_path, reponame):
setup_dir = os.path.split(setup_path)[-1] # Directory containing setup.py
prefix = reponame + '-' # Prefix to match
if setup_dir.startswith(prefix):
tag = setup_dir[len(prefix):]
# Assuming the tag is a version if it isn't empty, 'master' or 'main' and has a dot in it
if tag not in ['', 'master', 'main'] and ('.' in tag):
return tag
return None
@classmethod
def setup_version(cls, setup_path, reponame, archive_commit=None,
pkgname=None, dirty='report'):
info = {}
git_describe = None
pkgname = reponame if pkgname is None else pkgname
try:
# Will only work if in a git repo and git is available
git_describe = Version.get_setup_version(setup_path,
reponame,
describe=True,
dirty=dirty,
pkgname=pkgname,
archive_commit=archive_commit)
if git_describe is not None:
info['git_describe'] = git_describe
except: pass
if git_describe is None:
extracted_directory_tag = Version.extract_directory_tag(setup_path, reponame)
if extracted_directory_tag is not None:
info['extracted_directory_tag'] = extracted_directory_tag
try:
with open(os.path.join(setup_path, pkgname, '.version'), 'w') as f:
f.write(json.dumps({'extracted_directory_tag':extracted_directory_tag}))
except:
print('Error in setup_version: could not write .version file.')
info['version_string'] = Version.get_setup_version(setup_path,
reponame,
describe=False,
dirty=dirty,
pkgname=pkgname,
archive_commit=archive_commit)
try:
with open(os.path.join(setup_path, pkgname, '.version'), 'w') as f:
f.write(json.dumps(info))
except:
print('Error in setup_version: could not write .version file.')
return info['version_string']
def get_setup_version(location, reponame, pkgname=None, archive_commit=None):
"""Helper for use in setup.py to get the current version from either
git describe or the .version file (if available).
Set pkgname to the package name if it is different from the
repository name.
To ensure git information is included in a git archive, add
setup.py to .gitattributes (in addition to __init__):
```
__init__.py export-subst
setup.py export-subst
```
Then supply "$Format:%h$" for archive_commit.
"""
import warnings
pkgname = reponame if pkgname is None else pkgname
if archive_commit is None:
warnings.warn("No archive commit available; git archives will not contain version information")
return Version.setup_version(os.path.dirname(os.path.abspath(location)),reponame,pkgname=pkgname,archive_commit=archive_commit)
def get_setupcfg_version():
"""As get_setup_version(), but configure via setup.cfg.
If your project uses setup.cfg to configure setuptools, and hence has
at least a "name" key in the [metadata] section, you can
set the version as follows:
```
[metadata]
name = mypackage
version = attr: autover.version.get_setup_version2
```
If the repository name is different from the package name, specify
`reponame` as a [tool:autover] option:
```
[tool:autover]
reponame = mypackage
```
To ensure git information is included in a git archive, add
setup.cfg to .gitattributes (in addition to __init__):
```
__init__.py export-subst
setup.cfg export-subst
```
Then add the following to setup.cfg:
```
[tool:autover.configparser_workaround.archive_commit=$Format:%h$]
```
The above being a section heading rather than just a key is
because setuptools requires % to be escaped with %, or it can't
parse setup.cfg...but then git export-subst would not work.
"""
try:
import configparser
except ImportError:
import ConfigParser as configparser # python2 (also prevents dict-like access)
import re
cfg = "setup.cfg"
autover_section = 'tool:autover'
config = configparser.ConfigParser()
config.read(cfg)
pkgname = config.get('metadata','name')
reponame = config.get(autover_section,'reponame',vars={'reponame':pkgname}) if autover_section in config.sections() else pkgname
###
# hack archive_commit into section heading; see docstring
archive_commit = None
archive_commit_key = autover_section+'.configparser_workaround.archive_commit'
for section in config.sections():
if section.startswith(archive_commit_key):
archive_commit = re.match(r".*=\s*(\S*)\s*",section).group(1)
###
return get_setup_version(cfg,reponame=reponame,pkgname=pkgname,archive_commit=archive_commit)
# from param/version.py aa087db29976d9b7e0f59c29789dfd721c85afd0
class OldDeprecatedVersion:
"""
A simple approach to Python package versioning that supports PyPI
releases and additional information when working with version
control. When obtaining a package from PyPI, the version returned
is a string-formatted rendering of the supplied release tuple.
For instance, release (1,0) tagged as ``v1.0`` in the version
control system will return ``1.0`` for ``str(__version__)``. Any
number of items can be supplied in the release tuple, with either
two or three numeric versioning levels typical.
During development, a command like ``git describe`` will be used to
compute the number of commits since the last version tag, the
short commit hash, and whether the commit is dirty (has changes
not yet committed). Version tags must start with a lowercase 'v'
and have a period in them, e.g. v2.0, v0.9.8 or v0.1.
Development versions are supported by setting the dev argument to an
appropriate dev version number. The corresponding tag can be PEP440
compliant (using .devX) of the form v0.1.dev3, v1.9.0.dev2 etc but
it doesn't have to be as the dot may be omitted i.e v0.1dev3,
v1.9.0dev2 etc.
Also note that when version control system (VCS) information is
used, the comparison operators take into account the number of
commits since the last version tag. This approach is often useful
in practice to decide which version is newer for a single
developer, but will not necessarily be reliable when comparing
against a different fork or branch in a distributed VCS.
For git, if you want version control information available even in
an exported archive (e.g. a .zip file from GitHub), you can set
the following line in the .gitattributes file of your project::
__init__.py export-subst
"""
def __init__(self, release=None, fpath=None, commit=None,
reponame=None, dev=None, commit_count=0):
"""
:release: Release tuple (corresponding to the current VCS tag)
:commit Short SHA. Set to '$Format:%h$' for git archive support.
:fpath: Set to ``__file__`` to access version control information
:reponame: Used to verify VCS repository name.
:dev: Development version number. None if not a development version.
:commit_count Commits since last release. Set for dev releases.
"""
self.fpath = fpath
self._expected_commit = commit
self.expected_release = release
self._commit = None if commit in [None, "$Format:%h$"] else commit
self._commit_count = commit_count
self._release = None
self._dirty = False
self.reponame = reponame
self.dev = dev
@property
def release(self):
"Return the release tuple"
return self.fetch()._release
@property
def commit(self):
"A specification for this particular VCS version, e.g. a short git SHA"
return self.fetch()._commit
@property
def commit_count(self):
"Return the number of commits since the last release"
return self.fetch()._commit_count
@property
def dirty(self):
"True if there are uncommited changes, False otherwise"
return self.fetch()._dirty
def fetch(self):
"""
Returns a tuple of the major version together with the
appropriate SHA and dirty bit (for development version only).
"""
if self._release is not None:
return self
self._release = self.expected_release
if not self.fpath:
self._commit = self._expected_commit
return self
# Only git right now but easily extended to SVN, Mercurial, etc.
for cmd in ['git', 'git.cmd', 'git.exe']:
try:
self.git_fetch(cmd)
break
except OSError:
pass
return self
def git_fetch(self, cmd='git'):
try:
if self.reponame is not None:
# Verify this is the correct repository (since fpath could
# be an unrelated git repository, and param could just have
# been copied/installed into it).
output = run_cmd([cmd, 'remote', '-v'],
cwd=os.path.dirname(self.fpath))
repo_matches = ['/' + self.reponame + '.git' ,
# A remote 'server:reponame.git' can also be referred
# to (i.e. cloned) as `server:reponame`.
'/' + self.reponame + ' ']
if not any(m in output for m in repo_matches):
return self
output = run_cmd([cmd, 'describe', '--long', '--match', 'v*.*', '--dirty'],
cwd=os.path.dirname(self.fpath))
except Exception as e:
if e.args[1] == 'fatal: No names found, cannot describe anything.':
raise Exception("Cannot find any git version tags of format v*.*")
# If there is any other error, return (release value still useful)
return self
self._update_from_vcs(output)
def _update_from_vcs(self, output):
"Update state based on the VCS state e.g the output of git describe"
split = output[1:].split('-')
if 'dev' in split[0]:
dev_split = split[0].split('dev')
self.dev = int(dev_split[1])
split[0] = dev_split[0]
# Remove the pep440 dot if present
if split[0].endswith('.'):
split[0] = dev_split[0][:-1]
self._release = tuple(int(el) for el in split[0].split('.'))
self._commit_count = int(split[1])
self._commit = str(split[2][1:]) # Strip out 'g' prefix ('g'=>'git')
self._dirty = (split[-1]=='dirty')
return self
def __str__(self):
"""
Version in x.y.z string format. Does not include the "v"
prefix of the VCS version tags, for pip compatibility.
If the commit count is non-zero or the repository is dirty,
the string representation is equivalent to the output of::
git describe --long --match v*.* --dirty
(with "v" prefix removed).
"""
if self.release is None: return 'None'
release = '.'.join(str(el) for el in self.release)
release = '%s.dev%d' % (release, self.dev) if self.dev is not None else release
if (self._expected_commit is not None) and ("$Format" not in self._expected_commit):
pass # Concrete commit supplied - print full version string
elif (self.commit_count == 0 and not self.dirty):
return release
dirty_status = '-dirty' if self.dirty else ''
return '{}-{}-g{}{}'.format(release, self.commit_count if self.commit_count else 'x',
self.commit, dirty_status)
def __repr__(self):
return str(self)
def abbrev(self,dev_suffix=""):
"""
Abbreviated string representation, optionally declaring whether it is
a development version.
"""
return '.'.join(str(el) for el in self.release) + \
(dev_suffix if self.commit_count > 0 or self.dirty else "")
def __eq__(self, other):
"""
Two versions are considered equivalent if and only if they are
from the same release, with the same commit count, and are not
dirty. Any dirty version is considered different from any
other version, since it could potentially have any arbitrary
changes even for the same release and commit count.
"""
if self.dirty or other.dirty: return False
return ((self.release, self.commit_count, self.dev)
== (other.release, other.commit_count, other.dev))
def __gt__(self, other):
if self.release == other.release:
if self.dev == other.dev:
return self.commit_count > other.commit_count
elif None in [self.dev, other.dev]:
return self.dev is None
else:
return self.dev > other.dev
else:
return (self.release, self.commit_count) > (other.release, other.commit_count)
def __lt__(self, other):
if self==other:
return False
else:
return not (self > other)
def verify(self, string_version=None):
"""
Check that the version information is consistent with the VCS
before doing a release. If supplied with a string version,
this is also checked against the current version. Should be
called from setup.py with the declared package version before
releasing to PyPI.
"""
if string_version and string_version != str(self):
raise Exception("Supplied string version does not match current version.")
if self.dirty:
raise Exception("Current working directory is dirty.")
if self.release != self.expected_release:
raise Exception("Declared release does not match current release tag.")
if self.commit_count !=0:
raise Exception("Please update the VCS version tag before release.")
if self._expected_commit not in [None, "$Format:%h$"]:
raise Exception("Declared release does not match the VCS version tag")
param-2.1.1/pyproject.toml 0000664 0000000 0000000 00000011346 14636363363 0015551 0 ustar 00root root 0000000 0000000 [build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"
[project]
name = "param"
dynamic = ["version"]
description = "Make your Python code clearer and more reliable by declaring Parameters."
readme = "README.md"
license = { text = "BSD-3-Clause" }
requires-python = ">=3.8"
authors = [
{ name = "HoloViz", email = "developers@holoviz.org" },
]
maintainers = [
{ name = "HoloViz", email = "developers@holoviz.org" },
]
classifiers = [
"Development Status :: 5 - Production/Stable",
"Intended Audience :: Developers",
"Intended Audience :: Science/Research",
"License :: OSI Approved :: BSD License",
"Natural Language :: English",
"Operating System :: OS Independent",
"Programming Language :: Python :: 3",
"Programming Language :: Python :: 3.8",
"Programming Language :: Python :: 3.9",
"Programming Language :: Python :: 3.10",
"Programming Language :: Python :: 3.11",
"Programming Language :: Python :: 3.12",
"Topic :: Scientific/Engineering",
"Topic :: Software Development :: Libraries",
]
dependencies = []
[project.optional-dependencies]
examples = [
"aiohttp",
"pandas",
"panel",
]
doc = [
"param[examples]",
"nbsite ==0.8.4",
"sphinx-remove-toctrees",
]
tests = [
"coverage[toml]",
"pytest",
"pytest-asyncio",
]
tests-deser = [
"xlrd",
"openpyxl",
"odfpy",
"pyarrow",
"tables",
]
tests-examples = [
"pytest",
"pytest-asyncio",
"pytest-xdist",
"nbval",
"param[examples]",
]
tests-full = [
"param[tests]",
"param[tests-examples]",
"param[tests-deser]",
"numpy",
"pandas",
"ipython",
"jsonschema",
"gmpy",
"cloudpickle",
"nest_asyncio",
]
lint = [
"flake8",
"pre-commit",
]
all = [
"param[tests-full]",
"param[doc]",
"param[lint]",
]
[project.urls]
Homepage = "https://param.holoviz.org/"
Tracker = "https://github.com/holoviz/param/issues"
Releases = "https://github.com/holoviz/param/releases"
Source = "https://github.com/holoviz/param"
HoloViz = "https://holoviz.org/"
[tool.hatch.version]
source = "vcs"
[tool.hatch.build.targets.wheel]
include = [
"/param",
"/numbergen",
]
[tool.hatch.build.targets.sdist]
include = [
"/param",
"/numbergen",
"/tests",
]
[tool.hatch.build.hooks.vcs]
version-file = "param/_version.py"
[tool.hatch.envs.default]
dependencies = [
# Linters
"param[lint]",
# Base tests dependencies
"param[tests]",
# Examples tests dependencies
"param[tests-examples]",
# Deserializatoin dependencies
"param[tests-deser]",
# Additional tests dependencies, not including gmpy as
# it's tricky to install.
"ipython",
"jsonschema",
"numpy",
"pandas",
"cloudpickle",
"nest_asyncio",
# To keep __version__ up-to-date in editable installs
"setuptools_scm",
]
post-install-commands = [
"python -m pip install pre-commit",
"pre-commit install",
]
[tool.hatch.envs.default.scripts]
tests = "pytest {args:tests}"
examples = "pytest -n logical --dist loadscope --nbval-lax {args:doc}"
[tool.hatch.envs.docs]
template = "docs"
features = ["doc"]
python = "3.9"
[tool.hatch.envs.docs.scripts]
build = [
"sphinx-build -b html doc builtdocs",
]
[tool.hatch.envs.tests]
template = "tests"
dependencies = [
"param[tests]",
"ipython",
"jsonschema",
]
[[tool.hatch.envs.tests.matrix]]
python = [
"3.8",
"3.9",
"3.10",
"3.11",
"3.12",
"pypy3.9",
]
[tool.hatch.envs.tests.scripts]
tests = "pytest {args:tests}"
with_coverage = [
"coverage run --source=numbergen,param -m pytest -v {args:tests}",
"coverage report",
"coverage xml",
]
[tool.hatch.envs.tests.overrides]
# Only install these on non PyPy environments
name."^(?!pypy).*".dependencies = [
"numpy",
"pandas",
"xlrd",
"openpyxl",
"odfpy",
"pyarrow",
"cloudpickle",
"nest_asyncio",
]
# Only install gmpy on Linux on these version
# Only install tables (deser HDF5) on Linux on these version
matrix.python.dependencies = [
{ value = "gmpy", if = ["3.8", "3.9", "3.10"], platform = ["linux"] },
{ value = "tables", if = ["3.8", "3.9", "3.10", "3.11", "3.12"], platform = ["linux"] },
]
[tool.hatch.envs.tests_examples]
template = "tests_examples"
dependencies = [
"param[tests-examples]",
"ipython",
"jsonschema",
]
[[tool.hatch.envs.tests_examples.matrix]]
python = [
"3.8",
"3.9",
"3.10",
"3.11",
"3.12",
]
[tool.hatch.envs.tests_examples.scripts]
examples = "pytest -v -n logical --dist loadscope --nbval-lax {args:doc}"
[tool.pytest.ini_options]
python_files = "test*.py"
filterwarnings = [
"error",
]
xfail_strict = "true"
asyncio_mode = "auto"
[tool.coverage.report]
omit = ["param/version.py"]
param-2.1.1/tests/ 0000775 0000000 0000000 00000000000 14636363363 0013772 5 ustar 00root root 0000000 0000000 param-2.1.1/tests/__init__.py 0000664 0000000 0000000 00000000000 14636363363 0016071 0 ustar 00root root 0000000 0000000 param-2.1.1/tests/conftest.py 0000664 0000000 0000000 00000000471 14636363363 0016173 0 ustar 00root root 0000000 0000000 import param
import pytest
param.parameterized.warnings_as_exceptions = True
@pytest.fixture
def dataframe():
import pandas as pd
return pd.DataFrame({
'int': [1, 2, 3],
'float': [3.14, 6.28, 9.42],
'str': ['A', 'B', 'C']
}, index=[1, 2, 3], columns=['int', 'float', 'str'])
param-2.1.1/tests/testaddparameter.py 0000664 0000000 0000000 00000010007 14636363363 0017673 0 ustar 00root root 0000000 0000000 """
At the time of adding these tests, the implementation of add_parameter
had not changed since it was committed (f10b324 in July 2012). The tests
are checking that (not fully understood) implementation:
@classmethod
def _add_parameter(cls, param_name,param_obj):
'''
Add a new Parameter object into this object's class.
Supposed to result in a Parameter equivalent to one declared
in the class's source code.
'''
# CEBALERT: can't we just do
# setattr(cls,param_name,param_obj)? The metaclass's
# __setattr__ is actually written to handle that. (Would also
# need to do something about the params() cache. That cache
# is a pain, but it definitely improved the startup time; it
# would be worthwhile making sure no method except for one
# "add_param()" method has to deal with it (plus any future
# remove_param() method.)
type.__setattr__(cls,param_name,param_obj)
cls.__metaclass__._initialize_parameter(cls,param_name,param_obj)
# delete cached params()
try:
delattr(cls,'_%s__params'%cls.__name__)
except AttributeError:
pass
"""
import param
import pytest
def test_add_parameter_class():
class P(param.Parameterized):
x = param.Parameter()
P.param.add_parameter('y', param.Parameter())
assert 'y' in P.param
# Check the name is set
assert P.param.y.name == 'y'
def test_add_parameter_instance():
class P(param.Parameterized):
x = param.Parameter()
p = P()
p.param.add_parameter('y', param.Parameter())
assert 'y' in p.param
assert p.param.y.name == 'y'
def test_add_parameter_class_validation():
class P(param.Parameterized):
x = param.Parameter()
P.param.add_parameter('y', param.Number())
with pytest.raises(ValueError, match=r"Number parameter 'P.y' only takes numeric values, not ."):
P.y = 'test'
def test_add_parameter_instance_validation():
class P(param.Parameterized):
x = param.Parameter()
P.param.add_parameter('y', param.Number())
p = P()
with pytest.raises(ValueError, match=r"Number parameter 'P.y' only takes numeric values, not
![](\"https://holoviz.org/assets/panel.png\"/)
![](\"https://holoviz.org/assets/hvplot.png\"/)
![](\"https://holoviz.org/assets/holoviews.png\"/)
![](\"https://holoviz.org/assets/geoviews.png\"/)
![](\"https://holoviz.org/assets/datashader.png\"/)
![](\"https://holoviz.org/assets/param.png\"/)
![](\"https://holoviz.org/assets/colorcet.png\"/)
| | |
| --- | --- |
| Build Status | [](https://github.com/holoviz/param/actions/workflows/test.yaml)
| Coverage | [](https://codecov.io/gh/holoviz/param) ||
| Latest dev release | [](https://github.com/holoviz/param/tags) [](https://holoviz-dev.github.io/param/) |
| Latest release | [](https://github.com/holoviz/param/releases) [](https://pypi.python.org/pypi/param) [](https://anaconda.org/pyviz/param) [](https://anaconda.org/conda-forge/param) [](https://anaconda.org/anaconda/param) |
| Python | [](https://pypi.org/project/param/)
| Docs | [](https://github.com/holoviz/param/tree/gh-pages) [](https://param.holoviz.org) |
| Binder | [](https://mybinder.org/v2/gh/holoviz/param/main?labpath=doc) |
| Support | [](https://discourse.holoviz.org/) |
Param is a library providing Parameters: Python attributes extended to have features such as type and range checking, dynamically generated values, documentation strings, default values, etc., each of which is inherited from parent classes if not specified in a subclass.
Param contains only two required Python files, with no external dependencies, and is provided freely for both non-commercial and commercial use under a BSD license, so that it can easily be included as part of other projects.
Please see [param's website](https://param.holoviz.org) for official releases, installation instructions, documentation, and examples.
param-2.1.1/benchmarks/ 0000775 0000000 0000000 00000000000 14636363363 0014745 5 ustar 00root root 0000000 0000000 param-2.1.1/benchmarks/README.md 0000664 0000000 0000000 00000005674 14636363363 0016240 0 ustar 00root root 0000000 0000000 # Benchmarking
`Param` uses ASV (https://asv.readthedocs.io) for benchmarking.
## Preparation
Install `asv` into your environment with for example:
```
hatch shell
cd benchmarks
pip install asv
```
ASV then runs benchmarks in isolated virtual environments that it creates using `virtualenv`.
## Running benchmarks
To run all benchmarks against the default `main` branch:
```
cd benchmarks
asv run
```
The first time this is run it will create a machine file to store information about your machine. Then a virtual environment will be created and each benchmark will be run multiple times to obtain a statistically valid benchmark time.
To list the benchmark timings stored for the `main` branch use:
```
asv show main
```
ASV ships with its own simple webserver to interactively display the results in a webbrowser. To use this:
```
asv publish
asv preview
```
and then open a web browser at the URL specified.
If you want to quickly run all benchmarks once only to check for errors, etc, use:
```
asv dev
```
instead of `asv run`.
## Adding new benchmarks
Add new benchmarks to existing or new classes in the `benchmarks/benchmarks` directory. Any class member function with a name that starts with `time` will be identified as a timing benchmark when `asv` is run.
Data that is required to run benchmarks is usually created in the `setup()` member function. This ensures that the time taken to setup the data is not included in the benchmark time. The `setup()` function is called once for each invocation of each benchmark, the data are not cached.
At the top of each benchmark class there are lists of parameter names and values. Each benchmark is repeated for each unique combination of these parameters.
If you only want to run a subset of benchmarks, use syntax like:
```
asv run -b ShadeCategorical
```
where the text after the `-b` flag is used as a regex to match benchmark file, class and function names.
## Benchmarking code changes
You can compare the performance of code on different branches and in different commits. Usually if you want to determine how much faster a new algorithm is, the old code will be in the `main` branch and the new code will be in a new feature branch. Because ASV uses virtual environments and checks out the `param` source code into these virtual environments, your new code must be committed into the new feature branch locally.
To benchmark the latest commits on `main` and your new feature branch, edit `asv.conf.json` to change the line
```
"branches": ["main"],
```
into
```
"branches": ["main", "new_feature_branch"],
```
or similar.
Now when you `asv run` the benchmarks will be run against both branches in turn.
Then use
```
asv show
```
to list the commits that have been benchmarked, and
```
asv compare commit1 commit2
```
to give you a side-by-side comparison of the two commits.
You can run `asv` for single tags and compare them
```
asv run v0.0.1^!
asv run v0.0.2^!
asv compare v0.0.1 v0.0.2
```
```
asv run v0.0.2..HEAD
param-2.1.1/benchmarks/asv.conf.json 0000664 0000000 0000000 00000001544 14636363363 0017361 0 ustar 00root root 0000000 0000000 {
"version": 1,
"project": "param",
"project_url": "https://param.holoviz.org",
"repo": "..",
"dvcs": "git",
"repo_subdir": "",
"branches": ["main"],
"install_command": ["in-dir={env_dir} python -m pip install {wheel_file}"],
"uninstall_command": ["return-code=any python -m pip uninstall -y {project}"],
"build_command": [
"python -m pip install hatch hatch-vcs",
"PIP_NO_BUILD_ISOLATION=false python -mpip wheel --no-deps --no-index -w {build_cache_dir} {build_dir}"
],
"environment_type": "virtualenv",
"install_timeout": 600,
"show_commit_url": "https://github.com/holoviz/param/commit/",
// "pythons": ["3.8"],
"benchmark_dir": "benchmarks",
"env_dir": ".asv/env",
"results_dir": ".asv/results",
"html_dir": ".asv/html",
"hash_length": 8,
"build_cache_size": 2
}
param-2.1.1/benchmarks/benchmarks/ 0000775 0000000 0000000 00000000000 14636363363 0017062 5 ustar 00root root 0000000 0000000 param-2.1.1/benchmarks/benchmarks/__init__.py 0000664 0000000 0000000 00000000000 14636363363 0021161 0 ustar 00root root 0000000 0000000 param-2.1.1/benchmarks/benchmarks/benchmarks.py 0000664 0000000 0000000 00000044453 14636363363 0021563 0 ustar 00root root 0000000 0000000 # Write the benchmarking functions here.
# See "Writing benchmarks" in the asv docs for more information.
import param
class ImportSuite:
def timeraw_import_param(self):
return """
import param
"""
class ParameterSuite:
def time_instantiation(self):
param.Parameter()
class ParameterizedSuite:
def time_class_bare(self):
class P(param.Parameterized): pass
def time_class_with_1_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
def time_class_with_10_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
def time_class_with_100_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
x10 = param.Parameter()
x11 = param.Parameter()
x12 = param.Parameter()
x13 = param.Parameter()
x14 = param.Parameter()
x15 = param.Parameter()
x16 = param.Parameter()
x17 = param.Parameter()
x18 = param.Parameter()
x19 = param.Parameter()
x20 = param.Parameter()
x21 = param.Parameter()
x22 = param.Parameter()
x23 = param.Parameter()
x24 = param.Parameter()
x25 = param.Parameter()
x26 = param.Parameter()
x27 = param.Parameter()
x28 = param.Parameter()
x29 = param.Parameter()
x30 = param.Parameter()
x31 = param.Parameter()
x32 = param.Parameter()
x33 = param.Parameter()
x34 = param.Parameter()
x35 = param.Parameter()
x36 = param.Parameter()
x37 = param.Parameter()
x38 = param.Parameter()
x39 = param.Parameter()
x40 = param.Parameter()
x41 = param.Parameter()
x42 = param.Parameter()
x43 = param.Parameter()
x44 = param.Parameter()
x45 = param.Parameter()
x46 = param.Parameter()
x47 = param.Parameter()
x48 = param.Parameter()
x49 = param.Parameter()
x50 = param.Parameter()
x51 = param.Parameter()
x52 = param.Parameter()
x53 = param.Parameter()
x54 = param.Parameter()
x55 = param.Parameter()
x56 = param.Parameter()
x57 = param.Parameter()
x58 = param.Parameter()
x59 = param.Parameter()
x60 = param.Parameter()
x61 = param.Parameter()
x62 = param.Parameter()
x63 = param.Parameter()
x64 = param.Parameter()
x65 = param.Parameter()
x66 = param.Parameter()
x67 = param.Parameter()
x68 = param.Parameter()
x69 = param.Parameter()
x70 = param.Parameter()
x71 = param.Parameter()
x72 = param.Parameter()
x73 = param.Parameter()
x74 = param.Parameter()
x75 = param.Parameter()
x76 = param.Parameter()
x77 = param.Parameter()
x78 = param.Parameter()
x79 = param.Parameter()
x80 = param.Parameter()
x81 = param.Parameter()
x82 = param.Parameter()
x83 = param.Parameter()
x84 = param.Parameter()
x85 = param.Parameter()
x86 = param.Parameter()
x87 = param.Parameter()
x88 = param.Parameter()
x89 = param.Parameter()
x90 = param.Parameter()
x91 = param.Parameter()
x92 = param.Parameter()
x93 = param.Parameter()
x94 = param.Parameter()
x95 = param.Parameter()
x96 = param.Parameter()
x97 = param.Parameter()
x98 = param.Parameter()
x99 = param.Parameter()
class ParameterizedInstantiateSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
class P10(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
class P100(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
x10 = param.Parameter()
x11 = param.Parameter()
x12 = param.Parameter()
x13 = param.Parameter()
x14 = param.Parameter()
x15 = param.Parameter()
x16 = param.Parameter()
x17 = param.Parameter()
x18 = param.Parameter()
x19 = param.Parameter()
x20 = param.Parameter()
x21 = param.Parameter()
x22 = param.Parameter()
x23 = param.Parameter()
x24 = param.Parameter()
x25 = param.Parameter()
x26 = param.Parameter()
x27 = param.Parameter()
x28 = param.Parameter()
x29 = param.Parameter()
x30 = param.Parameter()
x31 = param.Parameter()
x32 = param.Parameter()
x33 = param.Parameter()
x34 = param.Parameter()
x35 = param.Parameter()
x36 = param.Parameter()
x37 = param.Parameter()
x38 = param.Parameter()
x39 = param.Parameter()
x40 = param.Parameter()
x41 = param.Parameter()
x42 = param.Parameter()
x43 = param.Parameter()
x44 = param.Parameter()
x45 = param.Parameter()
x46 = param.Parameter()
x47 = param.Parameter()
x48 = param.Parameter()
x49 = param.Parameter()
x50 = param.Parameter()
x51 = param.Parameter()
x52 = param.Parameter()
x53 = param.Parameter()
x54 = param.Parameter()
x55 = param.Parameter()
x56 = param.Parameter()
x57 = param.Parameter()
x58 = param.Parameter()
x59 = param.Parameter()
x60 = param.Parameter()
x61 = param.Parameter()
x62 = param.Parameter()
x63 = param.Parameter()
x64 = param.Parameter()
x65 = param.Parameter()
x66 = param.Parameter()
x67 = param.Parameter()
x68 = param.Parameter()
x69 = param.Parameter()
x70 = param.Parameter()
x71 = param.Parameter()
x72 = param.Parameter()
x73 = param.Parameter()
x74 = param.Parameter()
x75 = param.Parameter()
x76 = param.Parameter()
x77 = param.Parameter()
x78 = param.Parameter()
x79 = param.Parameter()
x80 = param.Parameter()
x81 = param.Parameter()
x82 = param.Parameter()
x83 = param.Parameter()
x84 = param.Parameter()
x85 = param.Parameter()
x86 = param.Parameter()
x87 = param.Parameter()
x88 = param.Parameter()
x89 = param.Parameter()
x90 = param.Parameter()
x91 = param.Parameter()
x92 = param.Parameter()
x93 = param.Parameter()
x94 = param.Parameter()
x95 = param.Parameter()
x96 = param.Parameter()
x97 = param.Parameter()
x98 = param.Parameter()
x99 = param.Parameter()
self.P1 = P1
self.P10 = P10
self.P100 = P100
def time_1_parameters(self):
self.P1()
def time_10_parameters(self):
self.P10()
def time_100_parameters(self):
self.P100()
class ParameterizedParamAccessSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
self.P1 = P1
self.p1 = P1()
def time_class(self):
self.P1.param
def time_instance(self):
self.p1.param
class ParameterizedParamContainsSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
self.P1 = P1
self.p1 = P1()
def time_class(self):
'x5' in self.P1.param
def time_instance(self):
'x5' in self.p1.param
class ParameterizedSetattrSuite:
def setup(self):
class P1(param.Parameterized):
x0 = param.Parameter()
self.P1 = P1
self.p1 = P1(x0=0)
def time_class(self):
self.P1.x0 = 1
def time_instance(self):
self.p1.x0 = 1
class ParameterizedDependsSuite:
def time_declarative_1_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
def time_watch_1_parameter(self):
class P(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
def time_declarative_10_parameters_separate_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
@param.depends('x1')
def foo1(self): pass
@param.depends('x2')
def foo2(self): pass
@param.depends('x3')
def foo3(self): pass
@param.depends('x4')
def foo4(self): pass
@param.depends('x5')
def foo5(self): pass
@param.depends('x6')
def foo6(self): pass
@param.depends('x7')
def foo7(self): pass
@param.depends('x8')
def foo8(self): pass
@param.depends('x9')
def foo9(self): pass
def time_declarative_10_parameters_shared_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9')
def foo(self): pass
def time_watch_10_parameters_separate_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
@param.depends('x1', watch=True)
def foo1(self): pass
@param.depends('x2', watch=True)
def foo2(self): pass
@param.depends('x3', watch=True)
def foo3(self): pass
@param.depends('x4', watch=True)
def foo4(self): pass
@param.depends('x5', watch=True)
def foo5(self): pass
@param.depends('x6', watch=True)
def foo6(self): pass
@param.depends('x7', watch=True)
def foo7(self): pass
@param.depends('x8', watch=True)
def foo8(self): pass
@param.depends('x9', watch=True)
def foo9(self): pass
def time_watch_10_parameters_shared_cb(self):
class P(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9', watch=True)
def foo(self): pass
class ParameterizedDependsInstantiateSuite:
def setup(self):
class P1Declarative(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
class P1Watch(param.Parameterized):
x0 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
class P10DeclarativeSeparate(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0')
def foo0(self): pass
@param.depends('x1')
def foo1(self): pass
@param.depends('x2')
def foo2(self): pass
@param.depends('x3')
def foo3(self): pass
@param.depends('x4')
def foo4(self): pass
@param.depends('x5')
def foo5(self): pass
@param.depends('x6')
def foo6(self): pass
@param.depends('x7')
def foo7(self): pass
@param.depends('x8')
def foo8(self): pass
@param.depends('x9')
def foo9(self): pass
class P10DeclarativeShared(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9')
def foo(self): pass
class P10WatchSeparate(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', watch=True)
def foo0(self): pass
@param.depends('x1', watch=True)
def foo1(self): pass
@param.depends('x2', watch=True)
def foo2(self): pass
@param.depends('x3', watch=True)
def foo3(self): pass
@param.depends('x4', watch=True)
def foo4(self): pass
@param.depends('x5', watch=True)
def foo5(self): pass
@param.depends('x6', watch=True)
def foo6(self): pass
@param.depends('x7', watch=True)
def foo7(self): pass
@param.depends('x8', watch=True)
def foo8(self): pass
@param.depends('x9', watch=True)
def foo9(self): pass
class P10WatchShared(param.Parameterized):
x0 = param.Parameter()
x1 = param.Parameter()
x2 = param.Parameter()
x3 = param.Parameter()
x4 = param.Parameter()
x5 = param.Parameter()
x6 = param.Parameter()
x7 = param.Parameter()
x8 = param.Parameter()
x9 = param.Parameter()
@param.depends('x0', 'x1', 'x2', 'x3', 'x4', 'x5', 'x6', 'x7', 'x8', 'x9', watch=True)
def foo(self): pass
self.P1Declarative = P1Declarative
self.P1Watch = P1Watch
self.P10DeclarativeSeparate = P10DeclarativeSeparate
self.P10DeclarativeShared = P10DeclarativeShared
self.P10WatchSeparate = P10WatchSeparate
self.P10WatchShared = P10WatchShared
def time_declarative_1_parameter(self):
self.P1Declarative()
def time_watch_1_parameter(self):
self.P1Watch()
def time_declarative_10_parameters_separate_cb(self):
self.P10DeclarativeSeparate()
def time_declarative_10_parameters_shared_cb(self):
self.P10DeclarativeShared()
def time_watch_10_parameters_separate_cb(self):
self.P10WatchSeparate()
def time_watch_10_parameters_shared_cb(self):
self.P10WatchShared()
class WatcherSuite:
def setup(self):
class P(param.Parameterized):
x0 = param.Parameter(0)
@param.depends('x0', watch=True)
def foo0(self): pass
self.p = P()
def time_trigger(self):
self.p.x0 += 1
param-2.1.1/binder/ 0000775 0000000 0000000 00000000000 14636363363 0014073 5 ustar 00root root 0000000 0000000 param-2.1.1/binder/environment.yml 0000664 0000000 0000000 00000000167 14636363363 0017166 0 ustar 00root root 0000000 0000000 name: param
channels:
- pyviz
- defaults
dependencies:
- python=3.9.7
- aiohttp=3.7.4
- panel=0.12.4
- pip
param-2.1.1/binder/postBuild 0000664 0000000 0000000 00000000050 14636363363 0015756 0 ustar 00root root 0000000 0000000 pip uninstall param --yes
pip install .
param-2.1.1/conda.recipe/ 0000775 0000000 0000000 00000000000 14636363363 0015162 5 ustar 00root root 0000000 0000000 param-2.1.1/conda.recipe/meta.yaml 0000664 0000000 0000000 00000002102 14636363363 0016767 0 ustar 00root root 0000000 0000000 {% set pyproject = load_file_data('../pyproject.toml', from_recipe_dir=True) %}
{% set buildsystem = pyproject['build-system'] %}
{% set project = pyproject['project'] %}
{% set name = project['name'] %}
{% set version = VERSION %}
package:
name: {{ name|lower }}
version: {{ version }}
source:
path: ..
build:
noarch: python
script: {{ PYTHON }} -m pip install . -vv
requirements:
build:
- python {{ project['requires-python'] }}
- pip
{% for dep in buildsystem['requires'] %}
- {{ dep }}
{% endfor %}
run:
- python {{ project['requires-python'] }}
test:
requires:
{% for dep in project['optional-dependencies']['tests'] %}
- {{ dep }}
{% endfor %}
source_files:
- pyproject.toml
- tests
imports:
- param
- numbergen
commands:
- python -c "import param; ver = param.__version__; assert ver != '0.0.0' and ver != 'unknown'"
- pytest tests
about:
home: {{ project['urls']['Homepage'] }}
summary: {{ project['description'] }}
license: {{ project['license']['text'] }}
license_file: LICENSE.txt
param-2.1.1/doc/ 0000775 0000000 0000000 00000000000 14636363363 0013375 5 ustar 00root root 0000000 0000000 param-2.1.1/doc/Promo.ipynb 0000664 0000000 0000000 00000026233 14636363363 0015542 0 ustar 00root root 0000000 0000000 {
"cells": [
{
"cell_type": "markdown",
"id": "6f716cf0",
"metadata": {},
"source": [
"![](\"https://raw.githubusercontent.com/holoviz/param/main/doc/_static/logo_horizontal.png\"){kind=logo}
"
]
},
{
"cell_type": "markdown",
"id": "fbaa7540",
"metadata": {},
"source": [
"# Introduction"
]
},
{
"cell_type": "markdown",
"id": "cddd48c6",
"metadata": {},
"source": [
"**Param is a library providing Parameters:**![](\"https://miro.medium.com/max/658/1*SsN2DG__Z5DyOI0uf7hbwQ.png\")
\n",
"\n",
"![](\"assets/param-is-powerful.png\")
](https://discourse.holoviz.org/)"
]
}
],
"metadata": {
"language_info": {
"name": "python",
"pygments_lexer": "ipython3"
}
},
"nbformat": 4,
"nbformat_minor": 5
}
param-2.1.1/doc/_static/ 0000775 0000000 0000000 00000000000 14636363363 0015023 5 ustar 00root root 0000000 0000000 param-2.1.1/doc/_static/favicon.ico 0000664 0000000 0000000 00000035356 14636363363 0017160 0 ustar 00root root 0000000 0000000 h 6 ¨ ž 00 ¨% F ( v4 i‚¨øÿІ‚‚‚‚‚ƒ{0?ëÿÿÿÿÿÿÿÿÿÿÿÿÿ‰Yq”ðý¿trrrrrrj' J^ :ˆ C‡ Œ ¸w ¸w »w ’| P… L† m ºw ¸w ¸w ¸w¸w¸w¸w ¸w ¸w ¸v ¸w¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸wK¸w»¸w̸wj¸w ¸w¸w¸w*¸w¼¸wݸwÛ¸wÛ¸wÛ¸wÛ¸wÛ¸wÛ¸wî¸wÿ¸wÿ¸wö¸wݸwÔ¸wb¸w/¸wɸwè¸wç¸wç¸wç¸wç¸wç¸wæ¸wó¸wÿ¸wÿ¸wø¸wç¸wá¸wm¸w¸w¸w)¸w(¸w(¸w(¸w(¸w(¸w'¸wP¸w»¸w˸wm¸w(¸w#¸w¸w ¸w ºx ˜d) U>[ P;^ tOD ºx ¸w ¸w ¸w¸w¸w¸w ¸w ¸w ’ ’ ’ ’ ’J ’^ ’ ’ ’ ‘ .'x 7,q Œ ’ ’ ’ ’ ’J ’` ’‹ ’ñ ’ý ’¼ ’d ’a ’a ’a ’a ’a ’a ’Y ’ ’> ’é ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’þ ’‡ ’ ’w ’’ ’± ’ø ’ÿ ’Ó ’• ’“ ’“ ’“ ’“ ’“ ’“ ’‹ ’9 ’ ’ ’ ’ ’v ’ ’5 ’ ’ ’ ’ ’ ’ ’ ‘ ’ ( @ Ž 0>) ‹ Œ ’ÓßËs Œ ,0/8¡üÿÿÿóŒ3/0000000000000% "ŸÕÙØÝøÿÿÿÿÿôÚØØØØØØØØØØØØØÙÎs
fùÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿØ5 ^ôÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÐ0 ‚¾ÃÂÆíÿÿÿÿÿçÄÂÃÃÃÃÃÃÃÃÃÃÃÃÄ´ZŽ uìÿÿÿÜa Œ Ž
]£µ˜B • Œ Ž Ž ¸w ¸w ¸w ¸w ¸t ¸t ¸t ¸t Œ Œ Œ Œ Œ ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ·w ·w ·w ·w Œ Œ Œ Œ ¸w ¸w ¸w ¸w ¸w¸w¸w¸w ¸x ¸w ¸w ¸w ·u ·u ·u ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸ww¸w¹¸wŸw¥¸wN¸w¸w ¸w ¸w ¸w ¸w ¸w ¶t
¸w ¸w¸w¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w1¸w©¸wù¸wÿ¸wÿ¸wÿ¸wà¸wb¸w ¸w ¸w ¸w·w¸w ¸w ¸w¸wƒ¸w̸wÒ¸wѸwѸwѸwѸwѸwѸwѸwѸwѸwѸwѸwѸwиwÛ¸wû¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wë¸wѸwѸwÒ¸w¿¸wW¸w¸w ¸wZ¸wñ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸w̸w-¸w ¸wb¸w÷¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÕ¸w2¸w ¸w ¸w£¸wâ¸wæ¸wå¸wå¸wå¸wå¸wå¸wå¸wå¸wå¸wå¸wå¸wå¸wå¸wå¸wê¸wü¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wó¸wå¸wå¸wæ¸wÙ¸wt¸w ¸w ¸x ¸w¸w0¸w5¸w4¸w4¸w4¸w4¸w4¸w4¸w4¸w4¸w4¸w4¸w4¸w4¸w3¸wB¸w«¸wù¸wÿ¸wÿ¸wÿ¸wà¸wk¸w3¸w4¸w5¸w(¸w¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸ww¸w¹¸wŸw¥¸wN¸w¸w ¸w ¸w ¸w ¸w ºy ¸w ¸w ¸w ¸w ’ ’ ’ ’
’
’
’
’ ¸w ¸w ¸w ¸w ¸w¸w¸w¸w ¸x ¸w ¸w ¸w ¸w ¸w ¸w ’ ’ ’ ’ ’ ’ ’ “ ’ ’ ’ ¸w ¸w ¸w ¸v ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w
‘
‘
‘
‘ ’ ’ ’ ’
’ ’ ’ ’ ’ ’ ’ ¸w ¸w ¸w ¸w ¸v ¸v ¸v ¸v ‘ ‘ ‘ ’ ’ ’ ’ ’ ’ ’ ’
’] ’£ ’µ ’˜ ’B ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’
’
’ ’ ’r ’ì ’ÿ ’ÿ ’ÿ ’Ü ’] ’ ’
’
’
’
’
’
’
’
’
’
’
’
’
’
’ ’ ’ ’ ’ ’g ’£ ’ª ’¨ ’± ’è ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’à ’¬ ’© ’© ’© ’© ’© ’© ’© ’© ’© ’© ’© ’© ’© ’ª ’˜ ’D ’ ’ ’U ’î ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’Ç ’* ’ ’k ’û ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’Ü ’8 ’ ’- ’¶ ’æ ’ê ’ê ’ì ’û ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ø ’ë ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’ê ’à ’Š ’ ’
“ ’ ’@ ’F ’E ’K ’¥ ’ü ’ÿ ’ÿ ’ÿ ’ó ’’ ’F ’E ’F ’F ’F ’F ’F ’F ’F ’F ’F ’F ’F ’F ’F ’8 ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’’ ’Ô ’ß ’Ë ’t ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ‘ ’ “ “ ’ ’ ’ ’ ’ ’ ’0 ’> ’) ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ “
À8ø ! ø À ( 0 ` $ Œ Ž Ž Œ‘ „ Ž Ž Z¦˜b Ž Ž !µýÿÿÿþÂ9Œ Œ Œ »ÿÿÿÿÿÿÿß> Œ Œ Ž hŒŒ‹¶ÿÿÿÿÿÿÿÿÿÒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŒŽh Œ .ÍÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÍ. ŠÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿŠ ¥ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ¤ wÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿw £ïüüüüûþÿÿÿÿÿÿÿÿÿÿüüüüüüüüüüüüüüüüüüüüüüüï£ 7UUTTSwïÿÿÿÿÿÿÿþ™STTTTTTTTTTTTTTTTTTTTUV7Ž Š ˆ môÿÿÿÿÿú˜ Œ Œ Œ ŒbÇëöïÌm Œ Œ -?4Œ Œ Œ ¸w ¸w ¸w ¸w ¸w ¸r ¸t ¸v ¸v ¸w ¸w ¸w¸w
¸w¸x ¸w ¹w ¸w ¸w ¸w ¸~ ¸w.¸w…¸wº¸wƸw±¸w}¸w(·w ¸w ¸w ·w ³v ¸w ¸w ¸w ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¹x ¸w ¸w¸wu¸wâ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÚ¸wQ¹w ¹x ¹x ¹x ¸w ¸w ¸w ²n ·u ¸w ¸w ¸w ¸w¸w¸w¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¹x¸ws¸wú¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wä¸wE¹x¹x¹x¸w¸w¸w¸w ¸w ¸w ¸w ¿x ¸w>¸w±¸wÕ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wÓ¸wò¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wç¸wÒ¸wÓ¸wÓ¸wÓ¸wÔ¸w±¸w>µ{ ¸w ¸w ¸w=¸wâ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wâ¸w=¸w ·v ¸w”¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸w“µx »w¸w¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸w¸x ¸w ¸wU¸wö¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wö¸wT¸w ¸w ¸w¸wx¸wܸwñ¸wñ¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wð¸wû¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wö¸wð¸wð¸wð¸wñ¸wñ¸wܸwx¸w¸w ¸w ¸w ¸v¸w ¸w7¸w7¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w6¸w4¸w}¸wù¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wä¸wX¸w4¸w6¸w6¸w7¸w7¸w ¸w¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w¸wv¸wâ¸wÿ¸wÿ¸wÿ¸wÿ¸wÿ¸wÚ¸wQ¸v ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¸w ¶
¸w.¸w…¸w»¸wǸw²¸w~¸w(¸w ¸w ¸w ¸v ¸v ¸w ¸w ¸w¸w
¸w¸w ¸w ¸w ¸w ¸w ¹w ¸w ¸w ¸w ¶v ¸v ’ ’ ’ ’ ’ ’ ’
’
’ ’ ’ ’ ’ ’- ’? ’4 ’ ’ ’ ’ ’ ’
’ ’a ’Æ ’ë ’ö ’ï ’Ì ’l ’ ’ ’
‘
’ ’ ’ ’ ’ ’ ’
’ ’m ’ô ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ú ’˜ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’
‘ ‘ ’ ’ ‘ ’ ’* ’* ’* ’* ’( ’_ ’ð ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’Œ ’) ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’* ’+ ’+ ’ • ’ ’ ’ ’ ’v ’Ñ ’é ’é ’è ’è ’è ’ô ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ú ’é ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’è ’é ’é ’Ñ ’v ’ ’ ’ ’a ’ü ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ü ’a ’ ‘ ’¡ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’¡ ’ { ’— ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’— y ’ ’D ’é ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’é ’D ’ “
“ ’@ ’š ’½ ’½ ’½ ’½ ’¼ ’Ð ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’à ’¼ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’½ ’š ’A “ ’ ’ ’ ’ “ ’ ’ ’ ’ ’ ’ ’» ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ÿ ’ß ’B ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ “ ” ’ ’ ’ ª ‘ ’ ’ ’ ’ ’ ’ ’ ’" ’µ ’ý ’ÿ ’ÿ ’ÿ ’þ ’Â ’9
’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ ’ “ “ ’ ª ‘ • ’ ’ ’[ ’ ’¦ ’™ ’b ’ ’ ’ ’ “ ’ ’ ’ ’
Ž ’ ’ š ‘ ÿÎçÿÿÿ ÿÿÿÿ ð ¿Àÿÿþ à À À € À À ŸÀÿÿü ÿ ÿÿÿ ÿØ3ÿÿÿ ÿïïÿÿÿ ÿÿÿÿÿÿ ÿÿÿý÷ÿ ÿÿÿ÷ ÿ ÿÿÿìÿ ßÿÿðü ° À À À € À À Ÿÿÿðü ÿÿÿÌÿ ÿÿÿç ÿ ÿÿÿùóÿ ÿÿÿÿÿÿ ÿïçÿÿÿ ÿØ7ÿÿÿ ÿ ÿÿÿ ŸÀÿÿý ° À À € À À À ° Ïàÿÿù ÿÿÿÿ ÿÎçÿÿÿ param-2.1.1/doc/_static/icon.png 0000664 0000000 0000000 00000012244 14636363363 0016464 0 ustar 00root root 0000000 0000000 ‰PNG
IHDR â æ ÈYÁ pHYs Õ篶 tEXtSoftware www.inkscape.org›î< 1IDATxœíÝy”\e™ðç½Õkuw:]]NX$,#‚Â茇å¸0dNÒY‰[˜9Nt1ƒY»³T<=ž™„Î
dÐ\FÃh $!‹àAT@=˜ †ˆ†D³twuW¯ÕétÝï?B4`j¿U·ªîóû÷.ß“œ~ÎwëÖïDDDDDDDDDDôâv€|°¹¦¦Þ.^i‰u™õ‹J ($"j†DqBKKïì{}`»—Š'‹¸qlÅDŸ¯dDo†âƒ “
![\"Param](\"../_static/param_help.png\")
"
]
},
{
"cell_type": "markdown",
"id": "3683dec7",
"metadata": {},
"source": [
"## Parameter value instantiation\n",
"\n",
"So much of the parameter metadata is there to help you control whether and how the parameter value is instantiated on Parameterized objects as they are created or new Parameterized subclasses as they are defined. Depending on how you want to use that Parameter and what values it might take, controlling instantiation can be very important when mutable values are involved. While the default behavior shown above is appropriate for **immutable attributes**, what happens if the value (unlike Python strings) is mutable? Things get a lot more complex."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "b9fa3c69",
"metadata": {},
"outputs": [],
"source": [
"s = [1, 2, 3]\n",
"\n",
"class C(Parameterized):\n",
" s1 = Parameter(s, doc=\"A sequence\")\n",
" s2 = Parameter(s, doc=\"Another sequence\")\n",
"\n",
"c = C()"
]
},
{
"cell_type": "markdown",
"id": "fe928bac",
"metadata": {},
"source": [
"Here, both parameters `s1` and `s2` effectively point to the same underlying sequence `s`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "ba3863a5",
"metadata": {},
"outputs": [],
"source": [
"c.s1 is c.s2"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0b9004be",
"metadata": {},
"outputs": [],
"source": [
"s[1] *= 5"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "81f40ddf",
"metadata": {},
"outputs": [],
"source": [
"s"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e69157b7",
"metadata": {},
"outputs": [],
"source": [
"c.s1"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "344bae37",
"metadata": {},
"outputs": [],
"source": [
"c.s1[2] = 'a'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "baf5b9f6",
"metadata": {},
"outputs": [],
"source": [
"c.s1"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5c87a5d6",
"metadata": {},
"outputs": [],
"source": [
"c.s2"
]
},
{
"cell_type": "markdown",
"id": "08324f49",
"metadata": {},
"source": [
"As you can see, there is only one actual sequence here, and `s`, `s1`, and `s2` all point to it. In some cases such behavior is desirable, e.g. if the mutable object is a specific global list (e.g. a set of search paths) with a unique identity and all of the parameters are meant to point to that specific item. In other cases, it's the contents of the mutable item that are important, and no sharing of contents is intended. Luckily, Param supports that case as well, if you provide `instantiate=True` (default is `False`):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5c92d85f",
"metadata": {},
"outputs": [],
"source": [
"s = [1,2,3]\n",
"\n",
"class D(Parameterized):\n",
" s1 = Parameter(default=s, doc=\"A sequence\", instantiate=True)\n",
" s2 = Parameter(default=s, doc=\"Another sequence\", instantiate=True)\n",
"\n",
"d = D()"
]
},
{
"cell_type": "markdown",
"id": "325b9bbe",
"metadata": {},
"source": [
"Now, parameters `s1` and `s2` point to their own copies of the sequence, independent of each other and of the original argument `s`:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "4c245a25",
"metadata": {},
"outputs": [],
"source": [
"d.s1 is d.s2"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "509c07ac",
"metadata": {},
"outputs": [],
"source": [
"s *= 2"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "311dbcba",
"metadata": {},
"outputs": [],
"source": [
"s"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9e5c5336",
"metadata": {},
"outputs": [],
"source": [
"d.s1"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "f9d142d7",
"metadata": {},
"outputs": [],
"source": [
"d.s1[2] = 'a'"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "3d9a12f0",
"metadata": {},
"outputs": [],
"source": [
"d.s2"
]
},
{
"cell_type": "markdown",
"id": "3792939f",
"metadata": {},
"source": [
"Of course, copying the data into each instance like that costs memory, and moreover prevents controlling all instances at once by setting a class attribute as we saw earlier, which is why `instantiate` is not True by default. As a rule of thumb, set `instantiate=True` if and only if (a) your Parameter can take mutable values, and (b) you want those values to be independent between Parameterized instances."
]
},
{
"cell_type": "markdown",
"id": "6cfed7ae",
"metadata": {},
"source": [
"## Parameter object instantiation\n",
"\n",
"`instantiate` controls how parameter _values_ behave, but similar issues arise for Parameter _objects_, which offer similar control via the `per_instance` metadata declaration. `per_instance` (`True` by default) provides a logically distinct Parameter object for every Parameterized instance, allowing each such instance to have different metadata for that parameter. For example, we can set the label separately for each instance without clobbering each other:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "2f5af5da",
"metadata": {},
"outputs": [],
"source": [
"d1 = D()\n",
"d2 = D()\n",
"d1.param.s1.label = \"sequence 1\"\n",
"d2.param.s1.label = \"(sequence 1)\"\n",
"d2.param.s1.label"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "9f224f3b",
"metadata": {},
"outputs": [],
"source": [
"d1.param.s1.label"
]
},
{
"cell_type": "markdown",
"id": "5ce34483",
"metadata": {},
"source": [
"This capability is useful for situations with dynamically updated metadata, e.g. if you need setting one parameter's value (e.g. 'Continent') to change the allowed values of another parameter (e.g. 'Country'). The underlying Parameter objects are copied lazily (only when actually changed), so that objects are not actually multiplied unless necessary. If you do want parameters to share a single Parameter object so that you can control its behavior globally, you can achieve that with `per_instance=False`, though the effects can be confusing in the same way as `instantiate=True` for mutable objects (above):"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "787e9813",
"metadata": {},
"outputs": [],
"source": [
"class E(Parameterized):\n",
" a = Parameter(default=3.14, label=\"pi\", per_instance=False)\n",
"\n",
"e1 = E()\n",
"e2 = E()\n",
"e2.param.a.label = \"Pie\"\n",
"e1.param.a.label"
]
},
{
"cell_type": "markdown",
"id": "c2e3d4a7",
"metadata": {},
"source": [
"## Instantiating with shared parameters\n",
"\n",
"When creating a large collection of Parameterized objects of the same type, the overhead of having separate parameters for each object can be significant. If you want, you can create the objects to share parameter values for efficiency, and also so that you can easily change a value on all such objects at the same time. \n",
"\n",
"As an example, let's say you've defined a Parameter value to be independent, such that changing one instance's value will not affect the others:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "5013fe69",
"metadata": {},
"outputs": [],
"source": [
"class S(param.Parameterized):\n",
" l = Parameter(default=[1,2,3], instantiate=True)\n",
"\n",
"ss = [S() for i in range(10)]\n",
"ss[0].l[2] = 5\n",
"ss[1].l"
]
},
{
"cell_type": "markdown",
"id": "6c7195fd",
"metadata": {},
"source": [
"Here changing the value of `l` on `ss[0]` doesn't affect `ss[1]` or any other instances.\n",
"\n",
"What if you as a user of this class are creating a very large number of similar objects and actually do want them to share the same parameter value, either to save memory or to make it easy to change all of their values at once? In that case you can use the context manager `shared_parameters`, and any Parameterized objects created within that context will share parameter values, such that changing one of them will affect all of them:"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "37e160d4",
"metadata": {},
"outputs": [],
"source": [
"with param.shared_parameters():\n",
" ps = [S() for i in range(10)]\n",
" \n",
"ps[0].l[2] = 5\n",
"ps[1].l"
]
},
{
"cell_type": "markdown",
"id": "ed4e296f",
"metadata": {},
"source": [
"This approach can provide significant speedup and memory savings in certain cases, but should only be used for good reasons, since it can cause confusion for any code expecting instances to be independent as they have been declared."
]
},
{
"cell_type": "markdown",
"id": "678b7a0e",
"metadata": {},
"source": [
"## Displaying Parameterized objects\n",
"\n",
"Most of the important behavior of Parameterized is to do with instantiation, getting, and setting, as described above. Parameterized also provides a few public methods for creating string representations of the Parameterized object and its parameters:\n",
"\n",
"- `Parameterized.__str__()`: A concise, non-executable representation of the name and class of this object\n",
"- `Parameterized.__repr__()`: A representation of this object and its parameter values as if it were Python code calling the constructor (`classname(parameter1=x,parameter2=y,...)`)\n",
"- `Parameterize.param._repr_html_()`: A rich HTML representation of the object with its parameters listed in a table together with their metadata.\n",
"- `Parameterized.param.pprint()`: Customizable, hierarchical pretty-printed representation of this Parameterized and (recursively) any of its parameters that are Parameterized objects. See [Serialization and Persistence](Serialization_and_Persistence.ipynb) for details on customizing `pprint`."
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0a1521ba",
"metadata": {},
"outputs": [],
"source": [
"import param\n",
"\n",
"class Q(param.Parameterized):\n",
" a = param.Number(default=39, bounds=(0,50), doc='Number a')\n",
" b = param.String(default=\"str\", doc='A string')\n",
"\n",
"class P(Q):\n",
" c = param.ClassSelector(default=Q(), class_=Q, doc='An instance of Q')\n",
" e = param.ClassSelector(default=param.Parameterized(), class_=param.Parameterized, doc='A Parameterized instance')\n",
" f = param.Range(default=(0,1), doc='A range')\n",
"\n",
"p = P(f=(2,3), c=P(f=(42,43)), name=\"demo\")"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "0b0d5b84",
"metadata": {},
"outputs": [],
"source": [
"p.__str__()"
]
},
{
"cell_type": "code",
"execution_count": null,
"id": "e119e92a",
"metadata": {},
"outputs": [],
"source": [
"p.__repr__()"
]
},
{
"cell_type": "markdown",
"id": "799c1eeb-71c2-40a3-ad06-fd3ed8eda501",
"metadata": {},
"source": [
"The HTML representation of a `Parameterized` instance or class is displayed when you call `