deploy: c5ba20d

Author: maximlt

.nojekyll

@@ -0,0 +1 @@
+param.holoviz.org

CNAME

@@ -0,0 +1 @@
+{}

_rediraffe_redirected.json

@@ -0,0 +1,9 @@
+# About
+
+Param is completely open source, available under a [BSD license](https://github.com/holoviz/param/blob/main/LICENSE.txt), freely for both commercial and non-commercial use. Param was originally developed at the University of Texas at Austin and the University of Edinburgh with funding from the US National Institutes of Health grant 1R01-MH66991. Param is now maintained by [Anaconda Inc.](https://anaconda.com) and by community contributors.
+
+Param is maintained as part of the [HoloViz](https://holoviz.org) family of tools. The [holoviz.org](https://holoviz.org) website shows how to use Param together with other libraries to solve complex problems, with detailed tutorials and examples. Each of the HoloViz tools builds on Param, as do many of the example projects at [examples.holoviz.org](https://examples.holoviz.org).
+
+If you have any questions or usage issues visit the [Param Discourse forum](https://discourse.holoviz.org/c/param), and if you want to report bugs or request new features, first see if it's already in our list of [open issues](https://github.com/holoviz/param/issues) and then add to the issue or open a new one if needed.
+
+If you like Param and have built something you want to share, tweet a link or screenshot of your latest creation at [@HoloViz_org](https://twitter.com/HoloViz_org). Thanks!

_sources/about.md.txt

@@ -0,0 +1,103 @@
+# Comparison to other approaches
+
+Param was first developed in 2003 for Python 2.1 as part of a long-running brain simulation [project](http://ioam.github.io/topographica), and was made into a separate package on [Github](https://github.com/holoviz/param/graphs/contributors) in 2012.  In the interim a variety of other libraries solving some of the same problems have been developed, including:
+
+- [Traits](https://github.com/enthought/traits)
+- [Traitlets](https://github.com/ipython/traitlets)
+- [attrs](https://github.com/python-attrs/attrs) (with optional [attrs-strict](https://github.com/bloomberg/attrs-strict))
+- [Django models](https://docs.djangoproject.com/en/3.1/topics/db/models)
+- [Pydantic](https://pydantic-docs.helpmanual.io)
+
+Plus, Python itself has incorporated mechanisms addressing some of the same issues:
+
+- [Python 3.6+ type annotations](https://www.python.org/dev/peps/pep-0526/)
+- [Python 3.7+ data classes](https://docs.python.org/3/library/dataclasses.html)
+- [Python 2.6+ namedtuples](https://docs.python.org/3/library/collections.html#namedtuple-factory-function-for-tuples-with-named-fields)
+- [Python 2.2+ properties](https://docs.python.org/3/library/functions.html#property)
+
+Each of these approaches overlaps with some but by no means all of the functionality provided by Param, as described below. Also see the comparisons provided with [attrs](https://www.attrs.org/en/stable/why.html) and by an [attr user](https://glyph.twistedmatrix.com/2016/08/attrs.html), which were written about `attrs` but also apply just as well to Param (with Param differing in also providing e.g. GUI support as listed below). [Other info](https://threeofwands.com/why-i-use-attrs-instead-of-pydantic/) comparing `attrs` to `pydantic` is also available.
+
+Here we will use the word "parameter" as a generic term for a Python attribute, a Param Parameter, a Traitlets/HasTraits trait, or an attr `attr.ib`.
+
+
+## Brevity of code
+
+Python properties can be used to express nearly anything Param or Traitlets can do, but they require at least an order of magnitude more code to do it. You can think of Param and Traitlets as a pre-written implementation of a Python property that implements a configurable parameter. Avoiding having to write that code each time is a big win, because configurable parameters are all over any Python codebase, and Parameter/attr.ib/pydantic/Traits-based approaches lead to much simpler and more maintainable codebases.
+
+Specifically, where Param or Traitlets can express an automatically validated type and bounds on an attribute in a simple and localized one-line declaration like `a = param.Integer(5, bounds=(1,10))`, implementing the same functionality using properties requires changes to the constructor plus separate explicit `get` and `set` methods, each with at least a half-dozen lines of validation code. Though this get/set/validate code may seem easy to write, it is difficult to read, difficult to maintain, and difficult to make comprehensive or exhaustive.
+In practice, most programmers simply skip validation or implement it only partially, leaving their code behaving in undefined ways for unexpected inputs. With Param or Traitlets, you don't have to choose between short/readable/maintainable code and heavily validated code; you can have both for far less work!
+
+`pydantic` and `attrs` provide many of these same benefits, though `attrs` type and bounds validation is treated as an extra step that is more general but also typically much more verbose.
+
+## Runtime checking
+
+Python 3 type annotations allow users to specify types for attributes and function returns, but these types are not normally checked at runtime, and so they do not have the same role of validating user input or programmer error as the type declarations in Params, Traits, Traitlets, pydantic, and attr. They also are limited to the type, so they cannot enforce constraints on range ('state' must be in the list ['Alabama', 'Alaska',...]). Thus even if type hinting is used, programmers still need to write code to actually validate the inputs to functions and methods, which is the role of packages like Param and Traitlets. Note that Pydantic focuses on [generating valid outputs at runtime](https://github.com/samuelcolvin/pydantic/issues/578) rather than detecting invalid inputs, so it may or may not be suitable for the same types of applications as the other libraries discussed here.
+
+
+## Generality and ease of integration with your project
+
+The various Python features listed above are part of the standard library with the versions indicated above, and so do not add any dependencies at all to your build process, as long as you restrict yourself to the Python versions where that support was added.
+
+Param, Traitlets, Pydantic, and attrs are all pure Python projects, with minimal dependencies, and so adding them to any project is generally straightforward. They also support a wide range of Python versions, making them usable in cases where the more recent Python-language features are not available.
+
+Django models offer some of the same ways to declare parameters and generate web-based GUIs (below), but require the extensive Django web framework and normally rely on a database and web server, which in practice limit their usage to users building dedicated web sites, unlike the no-dependency Param and attrs libraries that can be added to Python projects of any type.
+
+Traits is a very heavyweight solution, requiring installation and C compilation of a large suite of tools, which makes it difficult to include in separate projects.
+
+## GUI toolkits
+
+Several of these packages support automatically mapping parameters/traits/attributes into GUI widgets. Although any of them could in principle be supported for any GUI toolkit, only certain GUI interfaces are currently available:
+
+- Panel: Jupyter and Bokeh-server support for Param, mapping Parameters to widgets and ParameterizedObjects to sets of widgets
+- ParamTk: (unsupported) TKinter support for Param
+- IPywidgets: Jupyter support for Traitlets, but without automatic mapping from trait to widget
+- TraitsUI: wxWidgets and Qt support for Traits
+
+## Dynamic values
+
+Param, Traits, Traitlets, Pydantic, and attrs all allow any Python expression to be supplied for initializing parameters, allowing parameter default values to be computed at the time a module is first loaded. Pydantic, Traits, and Traitlets also allow a class author to add code for a given parameter to compute a default value on first access.
+
+  ```python
+  >>> from time import time, sleep
+  >>> import traitlets as tr
+  >>> class A(tr.HasTraits):
+  ...        instantiation_time = tr.Float()
+  ...        @tr.default('instantiation_time')
+  ...        def _look_up_time(self):
+  ...            return time()
+  ...
+  >>> a=A()
+  >>> time()
+  1634594159.2040331
+  >>> sleep(1)
+  >>> time()
+  1634594165.3485172
+  >>> a.instantiation_time
+  1634594167.812151
+  >>> a.instantiation_time
+  1634594167.812151
+  >>> sleep(1)
+  >>> b=A()
+  >>> b.instantiation_time
+  1634594178.427819
+  ```
+
+
+Param's equivalent decorator `@param.depends(on_init=True)` will run a method when the Parameterized class is instantiated, not on first access.
+On the other hand, Param does allow fully dynamic values for *any* access to a numeric Parameter instance, not just the original instantiation:
+
+  ```python
+  >>> from time import time
+  >>> import param
+  >>> class A(param.Parameterized):
+  ...     val=param.Number(0)
+  ...
+  >>> a=A()
+  >>> a.val
+  0
+  >>> a.val=lambda:time()
+  >>> a.val
+  1475587455.437027
+  >>> a.val
+  1475587456.501314
+  ```

_sources/comparisons.md.txt

@@ -0,0 +1,189 @@
+# Developer Guide
+
+Welcome. We are so happy you've decided to contribute.
+
+## Setting up a development environment
+
+This guide describes how to install and configure development environments.
+
+If you have any problems with the steps here, please reach out in the `dev` channel on [Discord](https://discord.gg/rb6gPXbdAr) or on [Discourse](https://discourse.holoviz.org/).
+
+## Preliminaries
+
+### Basic understanding of how to contribute to Open Source
+
+If this is your first open-source contribution, please study one or more of the below resources.
+
+- [How to Get Started with Contributing to Open Source | Video](https://youtu.be/RGd5cOXpCQw)
+- [Contributing to Open-Source Projects as a New Python Developer | Video](https://youtu.be/jTTf4oLkvaM)
+- [How to Contribute to an Open Source Python Project | Blog post](https://www.educative.io/blog/contribue-open-source-python-project)
+
+### Git
+
+The Param source code is stored in a [Git](https://git-scm.com) source control repository. The first step to working on Param is to install Git onto your system. There are different ways to do this, depending on whether you use Windows, Mac, or Linux.
+
+To install Git on any platform, refer to the [Installing Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) section of the [Pro Git Book](https://git-scm.com/book/en/v2).
+
+To contribute to Param, you will also need [Github account](https://github.com/join) and knowledge of the [_fork and pull request workflow_](https://docs.github.com/en/get-started/quickstart/contributing-to-projects).
+
+### Pixi
+
+Developing all aspects of Param requires a wide range of packages in different environments. To make this more manageable, Pixi manages the developer experience. To install Pixi, follow [this guide](https://pixi.sh/latest/#installation).
+
+#### Glossary
+
+- Tasks: A task is what can be run with `pixi run <task-name>`. Tasks can be anything from installing packages to running tests.
+- Environments: An environment is a set of packages installed in a virtual environment. Each environment has a name; you can run tasks in a specific environment with the `-e` flag.
+  For example, `pixi run -e test-core test-unit` will run the `test-unit` task in the `test-core` environment.
+- Lock-file: A lock-file is a file that contains all the information about the environments.
+
+For more information, see the [Pixi documentation](https://pixi.sh/latest/).
+
+:::{admonition} Note
+:class: info
+
+The first time you run `pixi`, it will create a `.pixi` directory in the source directory.
+This directory will contain all the files needed for the virtual environments.
+The `.pixi` directory can be large, so it is advised not to put the source directory into a cloud-synced directory.
+:::
+
+## Installing the Project
+
+### Cloning the Project
+
+The source code for the Param project is hosted on [GitHub](https://github.com/holoviz/param). The first thing you need to do is clone the repository.
+
+1. Go to [github.com/holoviz/param](https://github.com/holoviz/param)
+2. [Fork the repository](https://docs.github.com/en/get-started/quickstart/contributing-to-projects#forking-a-repository)
+3. Run in your terminal: `git clone https://github.com/<Your Username Here>/param`
+
+The instructions for cloning above created a `param` directory at your file system location.
+This `param` directory is the _source checkout_ for the remainder of this document, and your current working directory is this directory.
+
+### Fetch tags from upstream
+
+The version number of the package depends on [`git tags`](https://git-scm.com/book/en/v2/Git-Basics-Tagging), so you need to fetch the tags from the upstream repository:
+
+```bash
+git remote add upstream https://github.com/holoviz/param.git
+git fetch --tags upstream
+git push --tags
+```
+
+## Start developing
+
+To start developing, run the following command
+
+```bash
+pixi install
+```
+
+The first time you run it, it will create a `pixi.lock` file with information for all available environments. This command will take a minute or so to run.
+
+All available tasks can be found by running `pixi task list`, the following sections will give a brief introduction to the most common tasks.
+
+### Editable install
+
+It can be advantageous to install Param in [editable mode](https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs):
+
+```bash
+pixi run install
+```
+
+:::{admonition} Note
+:class: info
+
+Currently, this needs to be run for each environment. So, if you want to install in the `test-312` environment, you can add `--environment` / `-e` to the command:
+
+```bash
+pixi run -e test-313 install
+```
+
+You can find the list of environments in the **pixi.toml** file or via the command `pixi info`.
+
+:::
+
+## Linting
+
+Param uses [pre-commit](https://pre-commit.com/) to apply linting to Param code. Linting can be run for all the files with:
+
+```bash
+pixi run lint
+```
+
+Linting can also be set up to run automatically with each commit; this is the recommended way because if linting is not passing, the [Continuous Integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) will also fail.
+
+```bash
+pixi run lint-install
+```
+
+## Testing
+
+To help keep Param maintainable, all Pull Requests (PR) with code changes should typically be accompanied by relevant tests. While exceptions may be made for specific circumstances, the default assumption should be that a Pull Request without tests will not be merged.
+
+There are three types of tasks and five environments related to tests.
+
+### Unit tests
+
+Unit tests are usually small tests executed with [pytest](https://docs.pytest.org). They can be found in `param/tests/`.
+Unit tests can be run with the `test-unit` task:
+
+```bash
+pixi run test-unit
+```
+
+The task is available in the following environments:
+
+1. `test-39`, `test-310`, `test-311`, `test-312`, and `test-313`.
+1. `test-core` and `test-pypy`
+
+Where the first ones have the same environments except for different Python versions. `test-core` only has a core set of dependencies, and `test-pypy` is for testing on PyPy.
+
+If you haven't set the environment flag in the command, a menu will help you select which one of the environments to use.
+
+### Example tests
+
+Param's documentation consists mainly of Jupyter Notebooks. The example tests execute all the notebooks and fail if an error is raised. Example tests are possible thanks to [nbval](https://nbval.readthedocs.io/) and can be found in the `doc/` folder.
+Example tests can be run with the following command:
+
+```bash
+pixi run test-example
+```
+
+This task has the same environments as the unit tests except for `test-core` and `test-pypy`.
+
+## Documentation
+
+The documentation can be built with the command:
+
+```bash
+pixi run docs-build
+```
+
+## Build
+
+Param has two build tasks, for building packages for Pip and Conda.
+
+```bash
+pixi run build-pip
+pixi run build-conda
+```
+
+## Continuous Integration
+
+Every push to the `main` branch or any PR branch on GitHub automatically triggers a test build with [GitHub Actions](https://github.com/features/actions).
+
+You can see the list of all current and previous builds at [this URL](https://github.com/holoviz/param/actions)
+
+### Etiquette
+
+GitHub Actions provides free build workers for open-source projects. A few considerations will help you be considerate of others needing these limited resources:
+
+- Run the tests locally before opening or pushing to an opened PR.
+
+- Group commits to meaningful chunks of work before pushing to GitHub (i.e., don't push on every commit).
+
+## Useful Links
+
+- [Dev version of Param Site](https://holoviz-dev.github.io/param)
+  - Use this to explore new, not yet released features and docs