perspective-python 3.7.2__tar.gz → 3.7.4__tar.gz

{perspective_python-3.7.2 → perspective_python-3.7.4}/Cargo.toml

@@ -12,7 +12,7 @@
 
 [package]
 name = "perspective-python"
-version = "3.7.2"
+version = "3.7.4"
 edition = "2024"
 description = "A data visualization and analytics component, especially well-suited for large and/or streaming datasets."
 repository = "https://github.com/finos/perspective"
@@ -57,8 +57,8 @@ pyo3-build-config = "0.22.6"
 python-config-rs = "0.1.2"
 
 [dependencies]
-perspective-client = { version = "3.7.2" }
-perspective-server = { version = "3.7.2" }
+perspective-client = { version = "3.7.4" }
+perspective-server = { version = "3.7.4" }
 macro_rules_attribute = "0.2.0"
 async-lock = "2.5.0"
 pollster = "0.3.0"

{perspective_python-3.7.2 → perspective_python-3.7.4}/LICENSE_THIRDPARTY_cargo.yml

@@ -2911,14 +2911,14 @@ third_party_libraries:
 
       END OF TERMS AND CONDITIONS
 - package_name: perspective-client
-  package_version: 3.7.2
+  package_version: 3.7.4
   repository: https://github.com/finos/perspective
   license: Apache-2.0
   licenses:
   - license: Apache-2.0
     text: "# Apache License\n\n_Version 2.0, January 2004_  \n_&lt;<http://www.apache.org/licenses/>&gt;_\n\n### Terms and Conditions for use, reproduction, and distribution\n\n#### 1. Definitions\n\n“License” shall mean the terms and conditions for use, reproduction, and\ndistribution as defined by Sections 1 through 9 of this document.\n\n“Licensor” shall mean the copyright owner or entity authorized by the copyright\nowner that is granting the License.\n\n“Legal Entity” shall mean the union of the acting entity and all other entities\nthat control, are controlled by, or are under common control with that entity.\nFor the purposes of this definition, “control” means **(i)** the power, direct or\nindirect, to cause the direction or management of such entity, whether by\ncontract or otherwise, or **(ii)** ownership of fifty percent (50%) or more of the\noutstanding shares, or **(iii)** beneficial ownership of such entity.\n\n“You” (or “Your”) shall mean an individual or Legal Entity exercising\npermissions granted by this License.\n\n“Source” form shall mean the preferred form for making modifications, including\nbut not limited to software source code, documentation source, and configuration\nfiles.\n\n“Object” form shall mean any form resulting from mechanical transformation or\ntranslation of a Source form, including but not limited to compiled object code,\ngenerated documentation, and conversions to other media types.\n\n“Work” shall mean the work of authorship, whether in Source or Object form, made\navailable under the License, as indicated by a copyright notice that is included\nin or attached to the work (an example is provided in the Appendix below).\n\n“Derivative Works” shall mean any work, whether in Source or Object form, that\nis based on (or derived from) the Work and for which the editorial revisions,\nannotations, elaborations, or other modifications represent, as a whole, an\noriginal work of authorship. For the purposes of this License, Derivative Works\nshall not include works that remain separable from, or merely link (or bind by\nname) to the interfaces of, the Work and Derivative Works thereof.\n\n“Contribution” shall mean any work of authorship, including the original version\nof the Work and any modifications or additions to that Work or Derivative Works\nthereof, that is intentionally submitted to Licensor for inclusion in the Work\nby the copyright owner or by an individual or Legal Entity authorized to submit\non behalf of the copyright owner. For the purposes of this definition,\n“submitted” means any form of electronic, verbal, or written communication sent\nto the Licensor or its representatives, including but not limited to\ncommunication on electronic mailing lists, source code control systems, and\nissue tracking systems that are managed by, or on behalf of, the Licensor for\nthe purpose of discussing and improving the Work, but excluding communication\nthat is conspicuously marked or otherwise designated in writing by the copyright\nowner as “Not a Contribution.”\n\n“Contributor” shall mean Licensor and any individual or Legal Entity on behalf\nof whom a Contribution has been received by Licensor and subsequently\nincorporated within the Work.\n\n#### 2. Grant of Copyright License\n\nSubject to the terms and conditions of this License, each Contributor hereby\ngrants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\nirrevocable copyright license to reproduce, prepare Derivative Works of,\npublicly display, publicly perform, sublicense, and distribute the Work and such\nDerivative Works in Source or Object form.\n\n#### 3. Grant of Patent License\n\nSubject to the terms and conditions of this License, each Contributor hereby\ngrants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free,\nirrevocable (except as stated in this section) patent license to make, have\nmade, use, offer to sell, sell, import, and otherwise transfer the Work, where\nsuch license applies only to those patent claims licensable by such Contributor\nthat are necessarily infringed by their Contribution(s) alone or by combination\nof their Contribution(s) with the Work to which such Contribution(s) was\nsubmitted. If You institute patent litigation against any entity (including a\ncross-claim or counterclaim in a lawsuit) alleging that the Work or a\nContribution incorporated within the Work constitutes direct or contributory\npatent infringement, then any patent licenses granted to You under this License\nfor that Work shall terminate as of the date such litigation is filed.\n\n#### 4. Redistribution\n\nYou may reproduce and distribute copies of the Work or Derivative Works thereof\nin any medium, with or without modifications, and in Source or Object form,\nprovided that You meet the following conditions:\n\n-   **(a)** You must give any other recipients of the Work or Derivative Works a copy of\n    this License; and\n-   **(b)** You must cause any modified files to carry prominent notices stating that You\n    changed the files; and\n-   **(c)** You must retain, in the Source form of any Derivative Works that You distribute,\n    all copyright, patent, trademark, and attribution notices from the Source form\n    of the Work, excluding those notices that do not pertain to any part of the\n    Derivative Works; and\n-   **(d)** If the Work includes a “NOTICE” text file as part of its distribution, then any\n    Derivative Works that You distribute must include a readable copy of the\n    attribution notices contained within such NOTICE file, excluding those notices\n    that do not pertain to any part of the Derivative Works, in at least one of the\n    following places: within a NOTICE text file distributed as part of the\n    Derivative Works; within the Source form or documentation, if provided along\n    with the Derivative Works; or, within a display generated by the Derivative\n    Works, if and wherever such third-party notices normally appear. The contents of\n    the NOTICE file are for informational purposes only and do not modify the\n    License. You may add Your own attribution notices within Derivative Works that\n    You distribute, alongside or as an addendum to the NOTICE text from the Work,\n    provided that such additional attribution notices cannot be construed as\n    modifying the License.\n\nYou may add Your own copyright statement to Your modifications and may provide\nadditional or different license terms and conditions for use, reproduction, or\ndistribution of Your modifications, or for any such Derivative Works as a whole,\nprovided Your use, reproduction, and distribution of the Work otherwise complies\nwith the conditions stated in this License.\n\n#### 5. Submission of Contributions\n\nUnless You explicitly state otherwise, any Contribution intentionally submitted\nfor inclusion in the Work by You to the Licensor shall be under the terms and\nconditions of this License, without any additional terms or conditions.\nNotwithstanding the above, nothing herein shall supersede or modify the terms of\nany separate license agreement you may have executed with Licensor regarding\nsuch Contributions.\n\n#### 6. Trademarks\n\nThis License does not grant permission to use the trade names, trademarks,\nservice marks, or product names of the Licensor, except as required for\nreasonable and customary use in describing the origin of the Work and\nreproducing the content of the NOTICE file.\n\n#### 7. Disclaimer of Warranty\n\nUnless required by applicable law or agreed to in writing, Licensor provides the\nWork (and each Contributor provides its Contributions) on an “AS IS” BASIS,\nWITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied,\nincluding, without limitation, any warranties or conditions of TITLE,\nNON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are\nsolely responsible for determining the appropriateness of using or\nredistributing the Work and assume any risks associated with Your exercise of\npermissions under this License.\n\n#### 8. Limitation of Liability\n\nIn no event and under no legal theory, whether in tort (including negligence),\ncontract, or otherwise, unless required by applicable law (such as deliberate\nand grossly negligent acts) or agreed to in writing, shall any Contributor be\nliable to You for damages, including any direct, indirect, special, incidental,\nor consequential damages of any character arising as a result of this License or\nout of the use or inability to use the Work (including but not limited to\ndamages for loss of goodwill, work stoppage, computer failure or malfunction, or\nany and all other commercial damages or losses), even if such Contributor has\nbeen advised of the possibility of such damages.\n\n#### 9. Accepting Warranty or Additional Liability\n\nWhile redistributing the Work or Derivative Works thereof, You may choose to\noffer, and charge a fee for, acceptance of support, warranty, indemnity, or\nother liability obligations and/or rights consistent with this License. However,\nin accepting such obligations, You may act only on Your own behalf and on Your\nsole responsibility, not on behalf of any other Contributor, and only if You\nagree to indemnify, defend, and hold each Contributor harmless for any liability\nincurred by, or claims asserted against, such Contributor by reason of your\naccepting any such warranty or additional liability.\n\n_END OF TERMS AND CONDITIONS_\n\n### APPENDIX: How to apply the Apache License to your work\n\nTo apply the Apache License to your work, attach the following boilerplate\nnotice, with the fields enclosed by brackets `[]` replaced with your own\nidentifying information. (Don't include the brackets!) The text should be\nenclosed in the appropriate comment syntax for the file format. We also\nrecommend that a file or class name and description of purpose be included on\nthe same “printed page” as the copyright notice for easier identification within\nthird-party archives.\n\n    Copyright 2019 The Perspective Authors\n\n    Licensed under the Apache License, Version 2.0 (the \"License\");\n    you may not use this file except in compliance with the License.\n    You may obtain a copy of the License at\n\n      http://www.apache.org/licenses/LICENSE-2.0\n\n    Unless required by applicable law or agreed to in writing, software\n    distributed under the License is distributed on an \"AS IS\" BASIS,\n    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n    See the License for the specific language governing permissions and\n    limitations under the License.\n"
 - package_name: perspective-server
-  package_version: 3.7.2
+  package_version: 3.7.4
   repository: https://github.com/finos/perspective
   license: Apache-2.0
   licenses:

{perspective_python-3.7.2 → perspective_python-3.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: perspective-python
-Version: 3.7.2
+Version: 3.7.4
 Classifier: Development Status :: 5 - Production/Stable
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython

{perspective_python-3.7.2 → perspective_python-3.7.4}/docs/lib.md

@@ -5,8 +5,6 @@ high performance data-visualization and analytics component for the web browser.
 The examples in this module are in Python. See <a href="https://docs.rs/crate/perspective/latest"><code>perspective</code></a> docs for the Rust API.
 </div>
 
-# Python Examples
-
 A simple example which loads an [Apache Arrow](https://arrow.apache.org/) and
 computes a "Group By" operation, returning a new Arrow.
 
@@ -19,8 +17,6 @@ view = table.view(group_by = ["CounterParty", "Security"])
 arrow = view.to_arrow()
 ```
 
-# What is `perspective-python`
-
 Perspective for Python uses the exact same C++ data engine used by the
 [WebAssembly version](https://docs.rs/perspective-js/latest/perspective_js/) and
 [Rust version](https://docs.rs/crate/perspective/latest). The library consists
@@ -95,22 +91,6 @@ via [Conda Forge](https://conda-forge.org)
 conda install -c conda-forge perspective
 ``` -->
 
-### Jupyterlab
-
-`PerspectiveWidget` is a JupyterLab widget that implements the same API as
-`<perspective-viewer>`, allowing for fast, intuitive
-transformations/visualizations of various data formats within JupyterLab.
-
-`PerspectiveWidget` is compatible with Jupyterlab 3 and Jupyter Notebook 6 via a
-[prebuilt extension](https://jupyterlab.readthedocs.io/en/stable/extension/extension_dev.html#prebuilt-extensions).
-To use it, simply install `perspective-python` and the extensions should be
-available.
-
-`perspective-python`'s JupyterLab extension also provides convenient builtin
-viewers for `csv`, `json`, or `arrow` files. Simply right-click on a file with
-this extension and choose the appropriate `Perpective` option from the context
-menu.
-
 ## `Table`
 
 A `Table` can be created from a dataset or a schema, the specifics of which are
@@ -152,10 +132,10 @@ column_data = view.to_columns()
 row_data = view.to_json()
 ```
 
-### Pandas Support
+### Pandas and Polars Support
 
-Perspective's `Table` can be constructed from `pandas.DataFrame` objects.
-Internally, this just uses
+Perspective's `Table` can be constructed from `pandas.DataFrame` and
+`polars.DataFrame` objects. Internally, this just uses
 [`pyarrow::from_pandas`](https://arrow.apache.org/docs/python/pandas.html),
 which dictates behavior of this feature including type support.
 
@@ -345,154 +325,3 @@ const websocket = perspective.websocket("ws://localhost:8888/websocket");
 const table = websocket.open_table("data_source");
 document.getElementById("viewer").load(table);
 ```
-
-## `PerspectiveWidget`
-
-Building on top of the API provided by `perspective.Table`, the
-`PerspectiveWidget` is a JupyterLab plugin that offers the entire functionality
-of Perspective within the Jupyter environment. It supports the same API
-semantics of `<perspective-viewer>`, along with the additional data types
-supported by `perspective.Table`. `PerspectiveWidget` takes keyword arguments
-for the managed `View`:
-
-```python
-from perspective.widget import PerspectiveWidget
-w = perspective.PerspectiveWidget(
-    data,
-    plugin="X Bar",
-    aggregates={"datetime": "any"},
-    sort=[["date", "desc"]]
-)
-```
-
-### Creating a widget
-
-A widget is created through the `PerspectiveWidget` constructor, which takes as
-its first, required parameter a `perspective.Table`, a dataset, a schema, or
-`None`, which serves as a special value that tells the Widget to defer loading
-any data until later. In maintaining consistency with the Javascript API,
-Widgets cannot be created with empty dictionaries or lists—`None` should be used
-if the intention is to await data for loading later on. A widget can be
-constructed from a dataset:
-
-```python
-from perspective.widget import PerspectiveWidget
-PerspectiveWidget(data, group_by=["date"])
-```
-
-.. or a schema:
-
-```python
-PerspectiveWidget({"a": int, "b": str})
-```
-
-.. or an instance of a `perspective.Table`:
-
-```python
-table = perspective.table(data)
-PerspectiveWidget(table)
-```
-
-<!--
-## `PerspectiveRenderer`
-
-Perspective also exposes a JS-only `mimerender-extension`. This lets you view
-`csv`, `json`, and `arrow` files directly from the file browser. You can see
-this by right clicking one of these files and `Open With->CSVPerspective` (or
-`JSONPerspective` or `ArrowPerspective`). Perspective will also install itself
-as the default handler for opening `.arrow` files. -->
-
-## `PerspectiveTornadoHandler`
-
-Perspective ships with a pre-built Tornado handler that makes integration with
-`tornado.websockets` extremely easy. This allows you to run an instance of
-`Perspective` on a server using Python, open a websocket to a `Table`, and
-access the `Table` in JavaScript and through `<perspective-viewer>`. All
-instructions sent to the `Table` are processed in Python, which executes the
-commands, and returns its output through the websocket back to Javascript.
-
-### Python setup
-
-To use the handler, we need to first have a `Server`, a `Client` and an instance
-of a `Table`:
-
-```python
-SERVER = Server()
-CLIENT = SERVER.new_local_client()
-```
-
-Once the server has been created, create a `Table` instance with a name. The
-name that you host the table under is important — it acts as a unique accessor
-on the JavaScript side, which will look for a Table hosted at the websocket with
-the name you specify.
-
-```python
-TABLE = client.table(data, name="data_source_one")
-```
-
-After the server and table setup is complete, create a websocket endpoint and
-provide it a reference to `PerspectiveTornadoHandler`. You must provide the
-configuration object in the route tuple, and it must contain
-`"perspective_server"`, which is a reference to the `Server` you just created.
-
-```python
-from perspective.handlers.tornado import PerspectiveTornadoHandler
-
-app = tornado.web.Application([
-
-    # ... other handlers ...
-
-    # Create a websocket endpoint that the client JavaScript can access
-    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": SERVER, "check_origin": True})
-])
-```
-
-Optionally, the configuration object can also include `check_origin`, a boolean
-that determines whether the websocket accepts requests from origins other than
-where the server is hosted. See
-[Tornado docs](https://www.tornadoweb.org/en/stable/websocket.html#tornado.websocket.WebSocketHandler.check_origin)
-for more details.
-
-### JavaScript setup
-
-Once the server is up and running, you can access the Table you just hosted
-using `perspective.websocket` and `open_table()`. First, create a client that
-expects a Perspective server to accept connections at the specified URL:
-
-```javascript
-const websocket = await perspective.websocket("ws://localhost:8888/websocket");
-```
-
-Next open the `Table` we created on the server by name:
-
-```javascript
-const table = await websocket.open_table("data_source_one");
-```
-
-`table` is a proxy for the `Table` we created on the server. All operations that
-are possible through the JavaScript API are possible on the Python API as well,
-thus calling `view()`, `schema()`, `update()` etc. on `const table` will pass
-those operations to the Python `Table`, execute the commands, and return the
-result back to JavaScript. Similarly, providing this `table` to a
-`<perspective-viewer>` instance will allow virtual rendering:
-
-```javascript
-await viewer.load(table);
-```
-
-`perspective.websocket` expects a Websocket URL where it will send instructions.
-When `open_table` is called, the name to a hosted Table is passed through, and a
-request is sent through the socket to fetch the Table. No actual `Table`
-instance is passed inbetween the runtimes; all instructions are proxied through
-websockets.
-
-This provides for great flexibility — while `Perspective.js` is full of
-features, browser WebAssembly runtimes currently have some performance
-restrictions on memory and CPU feature utilization, and the architecture in
-general suffers when the dataset itself is too large to download to the client
-in full.
-
-The Python runtime does not suffer from memory limitations, utilizes Apache
-Arrow internal threadpools for threading and parallel processing, and generates
-architecture optimized code, which currently makes it more suitable as a
-server-side runtime than `node.js`.

{perspective_python-3.7.2 → perspective_python-3.7.4}/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@finos/perspective-python",
-    "version": "3.7.2",
+    "version": "3.7.4",
     "description": "",
     "private": true,
     "repository": {

perspective_python-3.7.4/perspective/__init__.py

@@ -0,0 +1,392 @@
+#  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+#  ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+#  ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+#  ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+#  ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+#  ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+#  ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+#  ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+#  ┃ This file is part of the Perspective library, distributed under the terms ┃
+#  ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+#  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+__version__ = "3.7.4"
+__all__ = [
+    "_jupyter_labextension_paths",
+    "Server",
+    "Client",
+    "Table",
+    "View",
+    "PerspectiveError",
+    "ProxySession",
+    "AsyncClient",
+    "AsyncServer",
+    "num_cpus",
+    "set_num_cpus",
+    "system_info",
+]
+
+__doc__ = """
+The Python language bindings for [Perspective](https://perspective.finos.org), a
+high performance data-visualization and analytics component for the web browser.
+
+A simple example which loads an [Apache Arrow](https://arrow.apache.org/) and
+computes a "Group By" operation, returning a new Arrow.
+
+```python
+from perspective import Server
+
+client = Server().new_local_client()
+table = client.table(arrow_bytes_data)
+view = table.view(group_by = ["CounterParty", "Security"])
+arrow = view.to_arrow()
+```
+
+Perspective for Python uses the exact same C++ data engine used by the
+[WebAssembly version](https://docs.rs/perspective-js/latest/perspective_js/) and
+[Rust version](https://docs.rs/crate/perspective/latest). The library consists
+of many of the same abstractions and API as in JavaScript, as well as
+Python-specific data loading support for [NumPy](https://numpy.org/),
+[Pandas](https://pandas.pydata.org/) (and
+[Apache Arrow](https://arrow.apache.org/), as in JavaScript).
+
+Additionally, `perspective-python` provides a session manager suitable for
+integration into server systems such as
+[Tornado websockets](https://www.tornadoweb.org/en/stable/websocket.html),
+[AIOHTTP](https://docs.aiohttp.org/en/stable/web_quickstart.html#websockets), or
+[Starlette](https://www.starlette.io/websockets/)/[FastAPI](https://fastapi.tiangolo.com/advanced/websockets/),
+which allows fully _virtual_ Perspective tables to be interacted with by
+multiple `<perspective-viewer>` in a web browser. You can also interact with a
+Perspective table from python clients, and to that end client libraries are
+implemented for both Tornado and AIOHTTP.
+
+As `<perspective-viewer>` will only consume the data necessary to render the
+current screen, this runtime mode allows _ludicrously-sized_ datasets with
+instant-load after they've been manifest on the server (at the expense of
+network latency on UI interaction).
+
+The included `PerspectiveWidget` allows running such a viewer in
+[JupyterLab](https://jupyterlab.readthedocs.io/en/stable/) in either server or
+client (via WebAssembly) mode, and the included `PerspectiveTornadoHandler`
+makes it simple to extend a Tornado server with virtual Perspective support.
+
+The `perspective` module exports several tools:
+
+-   `Server` the constructor for a new isntance of the Perspective data engine.
+-   The `perspective.widget` module exports `PerspectiveWidget`, the JupyterLab
+    widget for interactive visualization in a notebook cell.
+-   The `perspective.handlers` modules exports web frameworks handlers that
+    interface with a `perspective-client` in JavaScript.
+    -   `perspective.handlers.tornado.PerspectiveTornadoHandler` for
+        [Tornado](https://www.tornadoweb.org/)
+    -   `perspective.handlers.starlette.PerspectiveStarletteHandler` for
+        [Starlette](https://www.starlette.io/) and
+        [FastAPI](https://fastapi.tiangolo.com)
+    -   `perspective.handlers.aiohttp.PerspectiveAIOHTTPHandler` for
+        [AIOHTTP](https://docs.aiohttp.org),
+
+This user's guide provides an overview of the most common ways to use
+Perspective in Python: the `Table` API, the JupyterLab widget, and the Tornado
+handler.
+
+[More Examples](https://github.com/finos/perspective/tree/master/examples) are
+available on GitHub.
+
+## Installation
+
+`perspective-python` contains full bindings to the Perspective API, a JupyterLab
+widget, and a WebSocket handlers for several webserver libraries that allow you
+to host Perspective using server-side Python.
+
+`perspective-python` can be installed from [PyPI](https://pypi.org) via `pip`:
+
+```bash
+pip install perspective-python
+```
+
+## Quick Start
+
+A `Table` can be created from a dataset or a schema, the specifics of which are
+[discussed](#loading-data-with-table) in the JavaScript section of the user's
+guide. In Python, however, Perspective supports additional data types that are
+commonly used when processing data:
+
+-   `pandas.DataFrame`
+-   `polars.DataFrame`
+-   `bytes` (encoding an Apache Arrow)
+-   `objects` (either extracting a repr or via reference)
+-   `str` (encoding as a CSV)
+
+A `Table` is created in a similar fashion to its JavaScript equivalent:
+
+```python
+from datetime import date, datetime
+import numpy as np
+import pandas as pd
+import perspective
+
+data = pd.DataFrame({
+    "int": np.arange(100),
+    "float": [i * 1.5 for i in range(100)],
+    "bool": [True for i in range(100)],
+    "date": [date.today() for i in range(100)],
+    "datetime": [datetime.now() for i in range(100)],
+    "string": [str(i) for i in range(100)]
+})
+
+table = perspective.table(data, index="float")
+```
+
+Likewise, a `View` can be created via the `view()` method:
+
+```python
+view = table.view(group_by=["float"], filter=[["bool", "==", True]])
+column_data = view.to_columns()
+row_data = view.to_json()
+```
+
+#### Pandas and Polars Support
+
+Perspective's `Table` can be constructed from `pandas.DataFrame` and
+`polars.DataFrame` objects. Internally, this just uses
+[`pyarrow::from_pandas`](https://arrow.apache.org/docs/python/pandas.html),
+which dictates behavior of this feature including type support.
+
+If the dataframe does not have an index set, an integer-typed column named
+`"index"` is created. If you want to preserve the indexing behavior of the
+dataframe passed into Perspective, simply create the `Table` with
+`index="index"` as a keyword argument. This tells Perspective to once again
+treat the index as a primary key:
+
+```python
+data.set_index("datetime")
+table = perspective.table(data, index="index")
+```
+
+#### Time Zone Handling
+
+When parsing `"datetime"` strings, times are assumed _local time_ unless an
+explicit timezone offset is parsed. All `"datetime"` columns (regardless of
+input time zone) are _output_ to the user as `datetime.datetime` objects in
+_local time_ according to the Python runtime.
+
+This behavior is consistent with Perspective's behavior in JavaScript. For more
+details, see this in-depth
+[explanation](https://github.com/finos/perspective/pull/867) of
+`perspective-python` semantics around time zone handling.
+
+#### Callbacks and Events
+
+`perspective.Table` allows for `on_update` and `on_delete` callbacks to be
+set—simply call `on_update` or `on_delete` with a reference to a function or a
+lambda without any parameters:
+
+```python
+def update_callback():
+    print("Updated!")
+
+# set the update callback
+on_update_id = view.on_update(update_callback)
+
+
+def delete_callback():
+    print("Deleted!")
+
+# set the delete callback
+on_delete_id = view.on_delete(delete_callback)
+
+# set a lambda as a callback
+view.on_delete(lambda: print("Deleted x2!"))
+```
+
+If the callback is a named reference to a function, it can be removed with
+`remove_update` or `remove_delete`:
+
+```python
+view.remove_update(on_update_id)
+view.remove_delete(on_delete_id)
+```
+
+Callbacks defined with a lambda function cannot be removed, as lambda functions
+have no identifier.
+
+### Hosting `Table` and `View` instances
+
+`Server` "hosts" all `perspective.Table` and `perspective.View` instances
+created by its connected `Client`s. Hosted tables/views can have their methods
+called from other sources than the Python server, i.e. by a `perspective-viewer`
+running in a JavaScript client over the network, interfacing with
+`perspective-python` through the websocket API.
+
+The server has full control of all hosted `Table` and `View` instances, and can
+call any public API method on hosted instances. This makes it extremely easy to
+stream data to a hosted `Table` using `.update()`:
+
+```python
+server = perspective.Server()
+client = server.new_local_client()
+table = client.table(data, name="data_source")
+
+for i in range(10):
+    # updates continue to propagate automatically
+    table.update(new_data)
+```
+
+The `name` provided is important, as it enables Perspective in JavaScript to
+look up a `Table` and get a handle to it over the network. Otherwise, `name`
+will be assigned randomlu and the `Client` must look this up with
+`CLient.get_hosted_table_names()`
+
+### Client/Server Replicated Mode
+
+Using Tornado and
+[`PerspectiveTornadoHandler`](python.md#perspectivetornadohandler), as well as
+`Perspective`'s JavaScript library, we can set up "distributed" Perspective
+instances that allows multiple browser `perspective-viewer` clients to read from
+a common `perspective-python` server, as in the
+[Tornado Example Project](https://github.com/finos/perspective/tree/master/examples/python-tornado).
+
+This architecture works by maintaining two `Tables`—one on the server, and one
+on the client that mirrors the server's `Table` automatically using `on_update`.
+All updates to the table on the server are automatically applied to each client,
+which makes this architecture a natural fit for streaming dashboards and other
+distributed use-cases. In conjunction with [multithreading](#multi-threading),
+distributed Perspective offers consistently high performance over large numbers
+of clients and large datasets.
+
+_*server.py*_
+
+```python
+from perspective import Server
+from perspective.hadnlers.tornado import PerspectiveTornadoHandler
+
+# Create an instance of Server, and host a Table
+SERVER = Server()
+CLIENT = SERVER.new_local_client()
+
+# The Table is exposed at `localhost:8888/websocket` with the name `data_source`
+client.table(data, name = "data_source")
+
+app = tornado.web.Application([
+    # create a websocket endpoint that the client JavaScript can access
+    (r"/websocket", PerspectiveTornadoHandler, {"perspective_server": SERVER})
+])
+
+# Start the Tornado server
+app.listen(8888)
+loop = tornado.ioloop.IOLoop.current()
+loop.start()
+```
+
+Instead of calling `load(server_table)`, create a `View` using `server_table`
+and pass that into `viewer.load()`. This will automatically register an
+`on_update` callback that synchronizes state between the server and the client.
+
+_*index.html*_
+
+```html
+<perspective-viewer id="viewer" editable></perspective-viewer>
+
+<script type="module">
+    // Create a client that expects a Perspective server
+    // to accept connections at the specified URL.
+    const websocket = await perspective.websocket(
+        "ws://localhost:8888/websocket"
+    );
+
+    // Get a handle to the Table on the server
+    const server_table = await websocket.open_table("data_source_one");
+
+    // Create a new view
+    const server_view = await table.view();
+
+    // Create a Table on the client using `perspective.worker()`
+    const worker = await perspective.worker();
+    const client_table = await worker.table(view);
+
+    // Load the client table in the `<perspective-viewer>`.
+    document.getElementById("viewer").load(client_table);
+</script>
+```
+
+For a more complex example that offers distributed editing of the server
+dataset, see
+[client_server_editing.html](https://github.com/finos/perspective/blob/master/examples/python-tornado/client_server_editing.html).
+
+We also provide examples for Starlette/FastAPI and AIOHTTP:
+
+-   [Starlette Example Project](https://github.com/finos/perspective/tree/master/examples/python-starlette).
+-   [AIOHTTP Example Project](https://github.com/finos/perspective/tree/master/examples/python-aiohttp).
+
+### Server-only Mode
+
+The server setup is identical to [Distributed Mode](#distributed-mode) above,
+but instead of creating a view, the client calls `load(server_table)`: In
+Python, use `Server` and `PerspectiveTornadoHandler` to create a websocket
+server that exposes a `Table`. In this example, `table` is a proxy for the
+`Table` we created on the server. All API methods are available on _proxies_,
+the.g.us calling `view()`, `schema()`, `update()` on `table` will pass those
+operations to the Python `Table`, execute the commands, and return the result
+back to Javascript.
+
+```html
+<perspective-viewer id="viewer" editable></perspective-viewer>
+```
+
+```javascript
+const websocket = perspective.websocket("ws://localhost:8888/websocket");
+const table = websocket.open_table("data_source");
+document.getElementById("viewer").load(table);
+```
+
+"""
+
+
+import functools
+
+from .perspective import (
+    Client,
+    PerspectiveError,
+    ProxySession,
+    Server,
+    AsyncServer,
+    AsyncClient,
+    # NOTE: these are classes without constructors,
+    # so we import them just for type hinting
+    Table,  # noqa: F401
+    View,  # noqa: F401
+    num_cpus,
+    set_num_cpus,
+)
+
+
+GLOBAL_SERVER = Server()
+GLOBAL_CLIENT = GLOBAL_SERVER.new_local_client()
+
+
+@functools.wraps(Client.table)
+def table(*args, **kwargs):
+    return GLOBAL_CLIENT.table(*args, **kwargs)
+
+
+@functools.wraps(Client.open_table)
+def open_table(*args, **kwargs):
+    return GLOBAL_CLIENT.table(*args, **kwargs)
+
+
+@functools.wraps(Client.get_hosted_table_names)
+def get_hosted_table_names(*args, **kwargs):
+    return GLOBAL_CLIENT.get_hosted_table_names(*args, **kwargs)
+
+
+@functools.wraps(Client.system_info)
+def system_info(*args, **kwargs):
+    return GLOBAL_CLIENT.system_info(*args, **kwargs)
+
+
+def _jupyter_labextension_paths():
+    """
+    Read by `jupyter labextension develop`
+    @private
+    """
+    return [{"src": "labextension", "dest": "@finos/perspective-jupyterlab"}]