From 655ff3f39e38375434631854740b5f5a8c021c3c Mon Sep 17 00:00:00 2001 From: Marquess Valdez Date: Tue, 12 Dec 2023 09:31:28 -0800 Subject: [PATCH] doc(quil-py): Publish documentation to https://rigetti.github.io/quil-rs (#314) --- .github/workflows/publish-docs.yml | 47 +++++ .github/workflows/publish-quil-py.yml | 2 +- .gitignore | 5 + Cargo.lock | 4 +- quil-py/Cargo.toml | 2 +- quil-py/Makefile.toml | 5 + quil-py/README-py.md | 4 + quil-py/make_docs.py | 15 ++ quil-py/out/index.html | 7 + quil-py/out/quil.html | 237 +++++++++++++++++++++++++ quil-py/out/quil/quil.html | 233 ++++++++++++++++++++++++ quil-py/out/search.js | 46 +++++ quil-py/poetry.lock | 188 +++++++++++++++++++- quil-py/pyproject.toml | 1 + quil-py/quil.html | 237 +++++++++++++++++++++++++ quil-py/quil/__init__.py | 5 + quil-py/quil/expression/__init__.py | 1 + quil-py/quil/expression/__init__.pyi | 55 ++++-- quil-py/quil/instructions/__init__.py | 4 + quil-py/quil/instructions/__init__.pyi | 217 +++++++++++----------- quil-py/quil/program/__init__.py | 5 + quil-py/quil/validation/__init__.py | 5 + quil-py/quil/validation/identifier.py | 1 + 23 files changed, 1194 insertions(+), 132 deletions(-) create mode 100644 .github/workflows/publish-docs.yml create mode 100644 quil-py/make_docs.py create mode 100644 quil-py/out/index.html create mode 100644 quil-py/out/quil.html create mode 100644 quil-py/out/quil/quil.html create mode 100644 quil-py/out/search.js create mode 100644 quil-py/quil.html create mode 100644 quil-py/quil/expression/__init__.py create mode 100644 quil-py/quil/instructions/__init__.py create mode 100644 quil-py/quil/program/__init__.py create mode 100644 quil-py/quil/validation/__init__.py create mode 100644 quil-py/quil/validation/identifier.py diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 00000000..989f9418 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,47 @@ +name: Publish quil-py documentation + +on: + push: + branches: + - main + pull_request: + types: + - opened + - reopened + - synchronize + - closed + +jobs: + publish-docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v4 + with: + python-version: '3.11' + - name: Install poetry + uses: snok/install-poetry@v1 + - uses: Swatinem/rust-cache@v2 + - name: Install cargo-make + uses: actions-rs/cargo@v1 + with: + command: install + args: --debug cargo-make + - name: Build quil-py documentation + uses: actions-rs/cargo@v1 + with: + command: make + args: --cwd quil-py --makefile Makefile.toml docs + - name: Deploy preview + if: ${{ github.event_name == 'pull_request' }} + uses: rossjrw/pr-preview-action@v1 + with: + source-dir: quil-py/build/docs + preview-branch: quil-py-docs + - name: Deploy docs + if: ${{ github.event_name == 'push' }} + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: quil-py/build/docs + publish_branch: quil-py-docs diff --git a/.github/workflows/publish-quil-py.yml b/.github/workflows/publish-quil-py.yml index 55a01a80..67fc80f5 100644 --- a/.github/workflows/publish-quil-py.yml +++ b/.github/workflows/publish-quil-py.yml @@ -176,7 +176,7 @@ jobs: publish-rust-crate: name: Release runs-on: ubuntu-latest - needs: [ publish-python-package ] + needs: publish-python-package steps: - uses: actions/checkout@v3 with: diff --git a/.gitignore b/.gitignore index 0ecbf5f0..b9ebe0d1 100644 --- a/.gitignore +++ b/.gitignore @@ -12,3 +12,8 @@ node_modules # Python artifacts *.so __pycache__ +**./.null-ls-cache* + +# quil-py documentation +quil-py/build + diff --git a/Cargo.lock b/Cargo.lock index 0599df0a..98fa43f3 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1223,9 +1223,9 @@ checksum = "4bf2521270932c3c7bed1a59151222bd7643c79310f2916f01925e1e16255698" [[package]] name = "rigetti-pyo3" -version = "0.3.0" +version = "0.3.1" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "c8e75f9f76a8b8898607379b62c89d94dd43f924b377327fb9a2861f7c8cf2db" +checksum = "ff977cba40f2cadf214226cf51c9729a4f5730a5413f901246eed78cb6e795c9" dependencies = [ "num-complex", "num-traits", diff --git a/quil-py/Cargo.toml b/quil-py/Cargo.toml index 670b9326..8791f93b 100644 --- a/quil-py/Cargo.toml +++ b/quil-py/Cargo.toml @@ -27,7 +27,7 @@ strum.workspace = true # pyo3 dependencies should be updated together numpy = "0.20.0" pyo3 = "0.20.0" -rigetti-pyo3 = "0.3" +rigetti-pyo3 = "0.3.1" [build-dependencies] pyo3-build-config = "0.20.0" diff --git a/quil-py/Makefile.toml b/quil-py/Makefile.toml index 909d0e94..f93051ae 100644 --- a/quil-py/Makefile.toml +++ b/quil-py/Makefile.toml @@ -31,6 +31,11 @@ dependencies = [ "pytest", ] +[tasks.docs] +dependencies = ["poetry-install", "install-quil"] +command = "poetry" +args = ["run", "pdoc", "-o", "build/docs", "quil", "!quil.quil", "--logo", "https://qcs.rigetti.com/static/img/rigetti-logo.svg"] + [tasks.dev-flow] dependencies = ["dev-test-flow", "pytest-flow", "stubtest"] diff --git a/quil-py/README-py.md b/quil-py/README-py.md index 0ca772da..b51f462a 100644 --- a/quil-py/README-py.md +++ b/quil-py/README-py.md @@ -5,3 +5,7 @@ The `quil` package provides tools for constructing, manipulating, parsing, and printing [Quil](https://github.com/quil-lang/quil) programs. Internally, it is powered by [quil-rs](https://github.com/rigetti/quil-rs). This package is still in early development and breaking changes should be expected between minor versions. + +# Documentation + +Documentation for the current release of `quil` is published [here](https://rigetti.github.io/quil-rs/quil.html). Every version of `quil` ships [with type stubs](https://github.com/rigetti/quil-rs/tree/main/quil-py/quil) that provide type hints and documentation to Python tooling and editors that support the [Language Server Protocol](https://microsoft.github.io/language-server-protocol/) or similar. diff --git a/quil-py/make_docs.py b/quil-py/make_docs.py new file mode 100644 index 00000000..f27428e2 --- /dev/null +++ b/quil-py/make_docs.py @@ -0,0 +1,15 @@ +from pathlib import Path +import sys + +import pdoc + +import quil # noqa - we need to import quil for it to appear in sys.modules + + +if __name__ == "__main__": + print(dir(sys.modules["quil"])) + print(dir(sys.modules["quil.validation"])) + print([k for k in sys.modules.keys() if "quil" in k]) + del sys.modules["quil.validation"] + + pdoc.pdoc("quil", "!quil.quil", output_directory=Path("docs")) diff --git a/quil-py/out/index.html b/quil-py/out/index.html new file mode 100644 index 00000000..967079b4 --- /dev/null +++ b/quil-py/out/index.html @@ -0,0 +1,7 @@ + + + + + + + diff --git a/quil-py/out/quil.html b/quil-py/out/quil.html new file mode 100644 index 00000000..7ba583d2 --- /dev/null +++ b/quil-py/out/quil.html @@ -0,0 +1,237 @@ + + + + + + + quil API documentation + + + + + + + + + +
+
+

+quil

+ + + + + + + 
1from .quil import *
+
+ + +
+
+ + \ No newline at end of file diff --git a/quil-py/out/quil/quil.html b/quil-py/out/quil/quil.html new file mode 100644 index 00000000..93ef2bec --- /dev/null +++ b/quil-py/out/quil/quil.html @@ -0,0 +1,233 @@ + + + + + + + quil.quil API documentation + + + + + + + + + +
+
+

+quil.quil

+ + + + + +
+
+ + \ No newline at end of file diff --git a/quil-py/out/search.js b/quil-py/out/search.js new file mode 100644 index 00000000..9575c96b --- /dev/null +++ b/quil-py/out/search.js @@ -0,0 +1,46 @@ +window.pdocSearch = (function(){ +/** elasticlunr - http://weixsong.github.io * Copyright (C) 2017 Oliver Nightingale * Copyright (C) 2017 Wei Song * MIT Licensed */!function(){function e(e){if(null===e||"object"!=typeof e)return e;var t=e.constructor();for(var n in e)e.hasOwnProperty(n)&&(t[n]=e[n]);return t}var t=function(e){var n=new t.Index;return n.pipeline.add(t.trimmer,t.stopWordFilter,t.stemmer),e&&e.call(n,n),n};t.version="0.9.5",lunr=t,t.utils={},t.utils.warn=function(e){return function(t){e.console&&console.warn&&console.warn(t)}}(this),t.utils.toString=function(e){return void 0===e||null===e?"":e.toString()},t.EventEmitter=function(){this.events={}},t.EventEmitter.prototype.addListener=function(){var e=Array.prototype.slice.call(arguments),t=e.pop(),n=e;if("function"!=typeof t)throw new TypeError("last argument must be a function");n.forEach(function(e){this.hasHandler(e)||(this.events[e]=[]),this.events[e].push(t)},this)},t.EventEmitter.prototype.removeListener=function(e,t){if(this.hasHandler(e)){var n=this.events[e].indexOf(t);-1!==n&&(this.events[e].splice(n,1),0==this.events[e].length&&delete this.events[e])}},t.EventEmitter.prototype.emit=function(e){if(this.hasHandler(e)){var t=Array.prototype.slice.call(arguments,1);this.events[e].forEach(function(e){e.apply(void 0,t)},this)}},t.EventEmitter.prototype.hasHandler=function(e){return e in this.events},t.tokenizer=function(e){if(!arguments.length||null===e||void 0===e)return[];if(Array.isArray(e)){var n=e.filter(function(e){return null===e||void 0===e?!1:!0});n=n.map(function(e){return t.utils.toString(e).toLowerCase()});var i=[];return n.forEach(function(e){var n=e.split(t.tokenizer.seperator);i=i.concat(n)},this),i}return e.toString().trim().toLowerCase().split(t.tokenizer.seperator)},t.tokenizer.defaultSeperator=/[\s\-]+/,t.tokenizer.seperator=t.tokenizer.defaultSeperator,t.tokenizer.setSeperator=function(e){null!==e&&void 0!==e&&"object"==typeof e&&(t.tokenizer.seperator=e)},t.tokenizer.resetSeperator=function(){t.tokenizer.seperator=t.tokenizer.defaultSeperator},t.tokenizer.getSeperator=function(){return t.tokenizer.seperator},t.Pipeline=function(){this._queue=[]},t.Pipeline.registeredFunctions={},t.Pipeline.registerFunction=function(e,n){n in t.Pipeline.registeredFunctions&&t.utils.warn("Overwriting existing registered function: "+n),e.label=n,t.Pipeline.registeredFunctions[n]=e},t.Pipeline.getRegisteredFunction=function(e){return e in t.Pipeline.registeredFunctions!=!0?null:t.Pipeline.registeredFunctions[e]},t.Pipeline.warnIfFunctionNotRegistered=function(e){var n=e.label&&e.label in this.registeredFunctions;n||t.utils.warn("Function is not registered with pipeline. This may cause problems when serialising the index.\n",e)},t.Pipeline.load=function(e){var n=new t.Pipeline;return e.forEach(function(e){var i=t.Pipeline.getRegisteredFunction(e);if(!i)throw new Error("Cannot load un-registered function: "+e);n.add(i)}),n},t.Pipeline.prototype.add=function(){var e=Array.prototype.slice.call(arguments);e.forEach(function(e){t.Pipeline.warnIfFunctionNotRegistered(e),this._queue.push(e)},this)},t.Pipeline.prototype.after=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i+1,0,n)},t.Pipeline.prototype.before=function(e,n){t.Pipeline.warnIfFunctionNotRegistered(n);var i=this._queue.indexOf(e);if(-1===i)throw new Error("Cannot find existingFn");this._queue.splice(i,0,n)},t.Pipeline.prototype.remove=function(e){var t=this._queue.indexOf(e);-1!==t&&this._queue.splice(t,1)},t.Pipeline.prototype.run=function(e){for(var t=[],n=e.length,i=this._queue.length,o=0;n>o;o++){for(var r=e[o],s=0;i>s&&(r=this._queue[s](r,o,e),void 0!==r&&null!==r);s++);void 0!==r&&null!==r&&t.push(r)}return t},t.Pipeline.prototype.reset=function(){this._queue=[]},t.Pipeline.prototype.get=function(){return this._queue},t.Pipeline.prototype.toJSON=function(){return this._queue.map(function(e){return t.Pipeline.warnIfFunctionNotRegistered(e),e.label})},t.Index=function(){this._fields=[],this._ref="id",this.pipeline=new t.Pipeline,this.documentStore=new t.DocumentStore,this.index={},this.eventEmitter=new t.EventEmitter,this._idfCache={},this.on("add","remove","update",function(){this._idfCache={}}.bind(this))},t.Index.prototype.on=function(){var e=Array.prototype.slice.call(arguments);return this.eventEmitter.addListener.apply(this.eventEmitter,e)},t.Index.prototype.off=function(e,t){return this.eventEmitter.removeListener(e,t)},t.Index.load=function(e){e.version!==t.version&&t.utils.warn("version mismatch: current "+t.version+" importing "+e.version);var n=new this;n._fields=e.fields,n._ref=e.ref,n.documentStore=t.DocumentStore.load(e.documentStore),n.pipeline=t.Pipeline.load(e.pipeline),n.index={};for(var i in e.index)n.index[i]=t.InvertedIndex.load(e.index[i]);return n},t.Index.prototype.addField=function(e){return this._fields.push(e),this.index[e]=new t.InvertedIndex,this},t.Index.prototype.setRef=function(e){return this._ref=e,this},t.Index.prototype.saveDocument=function(e){return this.documentStore=new t.DocumentStore(e),this},t.Index.prototype.addDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.addDoc(i,e),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));this.documentStore.addFieldLength(i,n,o.length);var r={};o.forEach(function(e){e in r?r[e]+=1:r[e]=1},this);for(var s in r){var u=r[s];u=Math.sqrt(u),this.index[n].addToken(s,{ref:i,tf:u})}},this),n&&this.eventEmitter.emit("add",e,this)}},t.Index.prototype.removeDocByRef=function(e){if(e&&this.documentStore.isDocStored()!==!1&&this.documentStore.hasDoc(e)){var t=this.documentStore.getDoc(e);this.removeDoc(t,!1)}},t.Index.prototype.removeDoc=function(e,n){if(e){var n=void 0===n?!0:n,i=e[this._ref];this.documentStore.hasDoc(i)&&(this.documentStore.removeDoc(i),this._fields.forEach(function(n){var o=this.pipeline.run(t.tokenizer(e[n]));o.forEach(function(e){this.index[n].removeToken(e,i)},this)},this),n&&this.eventEmitter.emit("remove",e,this))}},t.Index.prototype.updateDoc=function(e,t){var t=void 0===t?!0:t;this.removeDocByRef(e[this._ref],!1),this.addDoc(e,!1),t&&this.eventEmitter.emit("update",e,this)},t.Index.prototype.idf=function(e,t){var n="@"+t+"/"+e;if(Object.prototype.hasOwnProperty.call(this._idfCache,n))return this._idfCache[n];var i=this.index[t].getDocFreq(e),o=1+Math.log(this.documentStore.length/(i+1));return this._idfCache[n]=o,o},t.Index.prototype.getFields=function(){return this._fields.slice()},t.Index.prototype.search=function(e,n){if(!e)return[];e="string"==typeof e?{any:e}:JSON.parse(JSON.stringify(e));var i=null;null!=n&&(i=JSON.stringify(n));for(var o=new t.Configuration(i,this.getFields()).get(),r={},s=Object.keys(e),u=0;u0&&t.push(e);for(var i in n)"docs"!==i&&"df"!==i&&this.expandToken(e+i,t,n[i]);return t},t.InvertedIndex.prototype.toJSON=function(){return{root:this.root}},t.Configuration=function(e,n){var e=e||"";if(void 0==n||null==n)throw new Error("fields should not be null");this.config={};var i;try{i=JSON.parse(e),this.buildUserConfig(i,n)}catch(o){t.utils.warn("user configuration parse failed, will use default configuration"),this.buildDefaultConfig(n)}},t.Configuration.prototype.buildDefaultConfig=function(e){this.reset(),e.forEach(function(e){this.config[e]={boost:1,bool:"OR",expand:!1}},this)},t.Configuration.prototype.buildUserConfig=function(e,n){var i="OR",o=!1;if(this.reset(),"bool"in e&&(i=e.bool||i),"expand"in e&&(o=e.expand||o),"fields"in e)for(var r in e.fields)if(n.indexOf(r)>-1){var s=e.fields[r],u=o;void 0!=s.expand&&(u=s.expand),this.config[r]={boost:s.boost||0===s.boost?s.boost:1,bool:s.bool||i,expand:u}}else t.utils.warn("field name in user configuration not found in index instance fields");else this.addAllFields2UserConfig(i,o,n)},t.Configuration.prototype.addAllFields2UserConfig=function(e,t,n){n.forEach(function(n){this.config[n]={boost:1,bool:e,expand:t}},this)},t.Configuration.prototype.get=function(){return this.config},t.Configuration.prototype.reset=function(){this.config={}},lunr.SortedSet=function(){this.length=0,this.elements=[]},lunr.SortedSet.load=function(e){var t=new this;return t.elements=e,t.length=e.length,t},lunr.SortedSet.prototype.add=function(){var e,t;for(e=0;e1;){if(r===e)return o;e>r&&(t=o),r>e&&(n=o),i=n-t,o=t+Math.floor(i/2),r=this.elements[o]}return r===e?o:-1},lunr.SortedSet.prototype.locationFor=function(e){for(var t=0,n=this.elements.length,i=n-t,o=t+Math.floor(i/2),r=this.elements[o];i>1;)e>r&&(t=o),r>e&&(n=o),i=n-t,o=t+Math.floor(i/2),r=this.elements[o];return r>e?o:e>r?o+1:void 0},lunr.SortedSet.prototype.intersect=function(e){for(var t=new lunr.SortedSet,n=0,i=0,o=this.length,r=e.length,s=this.elements,u=e.elements;;){if(n>o-1||i>r-1)break;s[n]!==u[i]?s[n]u[i]&&i++:(t.add(s[n]),n++,i++)}return t},lunr.SortedSet.prototype.clone=function(){var e=new lunr.SortedSet;return e.elements=this.toArray(),e.length=e.elements.length,e},lunr.SortedSet.prototype.union=function(e){var t,n,i;this.length>=e.length?(t=this,n=e):(t=e,n=this),i=t.clone();for(var o=0,r=n.toArray();o

\n"}, "quil.quil": {"fullname": "quil.quil", "modulename": "quil.quil", "kind": "module", "doc": "

\n"}}, "docInfo": {"quil": {"qualname": 0, "fullname": 1, "annotation": 0, "default_value": 0, "signature": 0, "bases": 0, "doc": 3}, "quil.quil": {"qualname": 0, "fullname": 2, "annotation": 0, "default_value": 0, "signature": 0, "bases": 0, "doc": 3}}, "length": 2, "save": true}, "index": {"qualname": {"root": {"docs": {}, "df": 0}}, "fullname": {"root": {"docs": {}, "df": 0, "q": {"docs": {}, "df": 0, "u": {"docs": {}, "df": 0, "i": {"docs": {}, "df": 0, "l": {"docs": {"quil": {"tf": 1}, "quil.quil": {"tf": 1.4142135623730951}}, "df": 2}}}}}}, "annotation": {"root": {"docs": {}, "df": 0}}, "default_value": {"root": {"docs": {}, "df": 0}}, "signature": {"root": {"docs": {}, "df": 0}}, "bases": {"root": {"docs": {}, "df": 0}}, "doc": {"root": {"docs": {"quil": {"tf": 1.7320508075688772}, "quil.quil": {"tf": 1.7320508075688772}}, "df": 2}}}, "pipeline": ["trimmer"], "_isPrebuiltIndex": true}; + + // mirrored in build-search-index.js (part 1) + // Also split on html tags. this is a cheap heuristic, but good enough. + elasticlunr.tokenizer.setSeperator(/[\s\-.;&_'"=,()]+|<[^>]*>/); + + let searchIndex; + if (docs._isPrebuiltIndex) { + console.info("using precompiled search index"); + searchIndex = elasticlunr.Index.load(docs); + } else { + console.time("building search index"); + // mirrored in build-search-index.js (part 2) + searchIndex = elasticlunr(function () { + this.pipeline.remove(elasticlunr.stemmer); + this.pipeline.remove(elasticlunr.stopWordFilter); + this.addField("qualname"); + this.addField("fullname"); + this.addField("annotation"); + this.addField("default_value"); + this.addField("signature"); + this.addField("bases"); + this.addField("doc"); + this.setRef("fullname"); + }); + for (let doc of docs) { + searchIndex.addDoc(doc); + } + console.timeEnd("building search index"); + } + + return (term) => searchIndex.search(term, { + fields: { + qualname: {boost: 4}, + fullname: {boost: 2}, + annotation: {boost: 2}, + default_value: {boost: 2}, + signature: {boost: 2}, + bases: {boost: 2}, + doc: {boost: 1}, + }, + expand: true + }); +})(); \ No newline at end of file diff --git a/quil-py/poetry.lock b/quil-py/poetry.lock index acf8127e..a75cd81e 100644 --- a/quil-py/poetry.lock +++ b/quil-py/poetry.lock @@ -1,9 +1,26 @@ -# This file is automatically @generated by Poetry 1.6.1 and should not be changed by hand. +# This file is automatically @generated by Poetry 1.4.0 and should not be changed by hand. + +[[package]] +name = "astunparse" +version = "1.6.3" +description = "An AST unparser for Python" +category = "dev" +optional = false +python-versions = "*" +files = [ + {file = "astunparse-1.6.3-py2.py3-none-any.whl", hash = "sha256:c2652417f2c8b5bb325c885ae329bdf3f86424075c4fd1a128674bc6fba4b8e8"}, + {file = "astunparse-1.6.3.tar.gz", hash = "sha256:5ad93a8456f0d084c3456d059fd9a92cce667963232cbf763eac3bc5b7940872"}, +] + +[package.dependencies] +six = ">=1.6.1,<2.0" +wheel = ">=0.23.0,<1.0" [[package]] name = "attrs" version = "22.2.0" description = "Classes Without Boilerplate" +category = "dev" optional = false python-versions = ">=3.6" files = [ @@ -22,6 +39,7 @@ tests-no-zope = ["cloudpickle", "cloudpickle", "hypothesis", "hypothesis", "mypy name = "black" version = "23.1.0" description = "The uncompromising code formatter." +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -71,6 +89,7 @@ uvloop = ["uvloop (>=0.15.2)"] name = "click" version = "8.1.3" description = "Composable command line interface toolkit" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -85,6 +104,7 @@ colorama = {version = "*", markers = "platform_system == \"Windows\""} name = "colorama" version = "0.4.6" description = "Cross-platform colored terminal text." +category = "dev" optional = false python-versions = "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,!=3.6.*,>=2.7" files = [ @@ -96,6 +116,7 @@ files = [ name = "exceptiongroup" version = "1.1.1" description = "Backport of PEP 654 (exception groups)" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -110,6 +131,7 @@ test = ["pytest (>=6)"] name = "iniconfig" version = "2.0.0" description = "brain-dead simple config-ini parsing" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -117,10 +139,99 @@ files = [ {file = "iniconfig-2.0.0.tar.gz", hash = "sha256:2d91e135bf72d31a410b17c16da610a82cb55f6b0477d1a902134b24a455b8b3"}, ] +[[package]] +name = "jinja2" +version = "3.1.2" +description = "A very fast and expressive template engine." +category = "dev" +optional = false +python-versions = ">=3.7" +files = [ + {file = "Jinja2-3.1.2-py3-none-any.whl", hash = "sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61"}, + {file = "Jinja2-3.1.2.tar.gz", hash = "sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852"}, +] + +[package.dependencies] +MarkupSafe = ">=2.0" + +[package.extras] +i18n = ["Babel (>=2.7)"] + +[[package]] +name = "markupsafe" +version = "2.1.3" +description = "Safely add untrusted strings to HTML/XML markup." +category = "dev" +optional = false +python-versions = ">=3.7" +files = [ + {file = "MarkupSafe-2.1.3-cp310-cp310-macosx_10_9_universal2.whl", hash = "sha256:cd0f502fe016460680cd20aaa5a76d241d6f35a1c3350c474bac1273803893fa"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:e09031c87a1e51556fdcb46e5bd4f59dfb743061cf93c4d6831bf894f125eb57"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:68e78619a61ecf91e76aa3e6e8e33fc4894a2bebe93410754bd28fce0a8a4f9f"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:65c1a9bcdadc6c28eecee2c119465aebff8f7a584dd719facdd9e825ec61ab52"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:525808b8019e36eb524b8c68acdd63a37e75714eac50e988180b169d64480a00"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-musllinux_1_1_aarch64.whl", hash = "sha256:962f82a3086483f5e5f64dbad880d31038b698494799b097bc59c2edf392fce6"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-musllinux_1_1_i686.whl", hash = "sha256:aa7bd130efab1c280bed0f45501b7c8795f9fdbeb02e965371bbef3523627779"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:c9c804664ebe8f83a211cace637506669e7890fec1b4195b505c214e50dd4eb7"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-win32.whl", hash = "sha256:10bbfe99883db80bdbaff2dcf681dfc6533a614f700da1287707e8a5d78a8431"}, + {file = "MarkupSafe-2.1.3-cp310-cp310-win_amd64.whl", hash = "sha256:1577735524cdad32f9f694208aa75e422adba74f1baee7551620e43a3141f559"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-macosx_10_9_universal2.whl", hash = "sha256:ad9e82fb8f09ade1c3e1b996a6337afac2b8b9e365f926f5a61aacc71adc5b3c"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:3c0fae6c3be832a0a0473ac912810b2877c8cb9d76ca48de1ed31e1c68386575"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:b076b6226fb84157e3f7c971a47ff3a679d837cf338547532ab866c57930dbee"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bfce63a9e7834b12b87c64d6b155fdd9b3b96191b6bd334bf37db7ff1fe457f2"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:338ae27d6b8745585f87218a3f23f1512dbf52c26c28e322dbe54bcede54ccb9"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:e4dd52d80b8c83fdce44e12478ad2e85c64ea965e75d66dbeafb0a3e77308fcc"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:df0be2b576a7abbf737b1575f048c23fb1d769f267ec4358296f31c2479db8f9"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:5bbe06f8eeafd38e5d0a4894ffec89378b6c6a625ff57e3028921f8ff59318ac"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-win32.whl", hash = "sha256:dd15ff04ffd7e05ffcb7fe79f1b98041b8ea30ae9234aed2a9168b5797c3effb"}, + {file = "MarkupSafe-2.1.3-cp311-cp311-win_amd64.whl", hash = "sha256:134da1eca9ec0ae528110ccc9e48041e0828d79f24121a1a146161103c76e686"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_universal2.whl", hash = "sha256:f698de3fd0c4e6972b92290a45bd9b1536bffe8c6759c62471efaa8acb4c37bc"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:aa57bd9cf8ae831a362185ee444e15a93ecb2e344c8e52e4d721ea3ab6ef1823"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ffcc3f7c66b5f5b7931a5aa68fc9cecc51e685ef90282f4a82f0f5e9b704ad11"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:47d4f1c5f80fc62fdd7777d0d40a2e9dda0a05883ab11374334f6c4de38adffd"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:1f67c7038d560d92149c060157d623c542173016c4babc0c1913cca0564b9939"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:9aad3c1755095ce347e26488214ef77e0485a3c34a50c5a5e2471dff60b9dd9c"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:14ff806850827afd6b07a5f32bd917fb7f45b046ba40c57abdb636674a8b559c"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8f9293864fe09b8149f0cc42ce56e3f0e54de883a9de90cd427f191c346eb2e1"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-win32.whl", hash = "sha256:715d3562f79d540f251b99ebd6d8baa547118974341db04f5ad06d5ea3eb8007"}, + {file = "MarkupSafe-2.1.3-cp312-cp312-win_amd64.whl", hash = "sha256:1b8dd8c3fd14349433c79fa8abeb573a55fc0fdd769133baac1f5e07abf54aeb"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-macosx_10_9_x86_64.whl", hash = "sha256:8e254ae696c88d98da6555f5ace2279cf7cd5b3f52be2b5cf97feafe883b58d2"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:cb0932dc158471523c9637e807d9bfb93e06a95cbf010f1a38b98623b929ef2b"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:9402b03f1a1b4dc4c19845e5c749e3ab82d5078d16a2a4c2cd2df62d57bb0707"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:ca379055a47383d02a5400cb0d110cef0a776fc644cda797db0c5696cfd7e18e"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-musllinux_1_1_aarch64.whl", hash = "sha256:b7ff0f54cb4ff66dd38bebd335a38e2c22c41a8ee45aa608efc890ac3e3931bc"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-musllinux_1_1_i686.whl", hash = "sha256:c011a4149cfbcf9f03994ec2edffcb8b1dc2d2aede7ca243746df97a5d41ce48"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-musllinux_1_1_x86_64.whl", hash = "sha256:56d9f2ecac662ca1611d183feb03a3fa4406469dafe241673d521dd5ae92a155"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-win32.whl", hash = "sha256:8758846a7e80910096950b67071243da3e5a20ed2546e6392603c096778d48e0"}, + {file = "MarkupSafe-2.1.3-cp37-cp37m-win_amd64.whl", hash = "sha256:787003c0ddb00500e49a10f2844fac87aa6ce977b90b0feaaf9de23c22508b24"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-macosx_10_9_universal2.whl", hash = "sha256:2ef12179d3a291be237280175b542c07a36e7f60718296278d8593d21ca937d4"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-macosx_10_9_x86_64.whl", hash = "sha256:2c1b19b3aaacc6e57b7e25710ff571c24d6c3613a45e905b1fde04d691b98ee0"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:8afafd99945ead6e075b973fefa56379c5b5c53fd8937dad92c662da5d8fd5ee"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:8c41976a29d078bb235fea9b2ecd3da465df42a562910f9022f1a03107bd02be"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:d080e0a5eb2529460b30190fcfcc4199bd7f827663f858a226a81bc27beaa97e"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-musllinux_1_1_aarch64.whl", hash = "sha256:69c0f17e9f5a7afdf2cc9fb2d1ce6aabdb3bafb7f38017c0b77862bcec2bbad8"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-musllinux_1_1_i686.whl", hash = "sha256:504b320cd4b7eff6f968eddf81127112db685e81f7e36e75f9f84f0df46041c3"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:42de32b22b6b804f42c5d98be4f7e5e977ecdd9ee9b660fda1a3edf03b11792d"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-win32.whl", hash = "sha256:ceb01949af7121f9fc39f7d27f91be8546f3fb112c608bc4029aef0bab86a2a5"}, + {file = "MarkupSafe-2.1.3-cp38-cp38-win_amd64.whl", hash = "sha256:1b40069d487e7edb2676d3fbdb2b0829ffa2cd63a2ec26c4938b2d34391b4ecc"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-macosx_10_9_universal2.whl", hash = "sha256:8023faf4e01efadfa183e863fefde0046de576c6f14659e8782065bcece22198"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:6b2b56950d93e41f33b4223ead100ea0fe11f8e6ee5f641eb753ce4b77a7042b"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:9dcdfd0eaf283af041973bff14a2e143b8bd64e069f4c383416ecd79a81aab58"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:05fb21170423db021895e1ea1e1f3ab3adb85d1c2333cbc2310f2a26bc77272e"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-manylinux_2_5_i686.manylinux1_i686.manylinux_2_17_i686.manylinux2014_i686.whl", hash = "sha256:282c2cb35b5b673bbcadb33a585408104df04f14b2d9b01d4c345a3b92861c2c"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-musllinux_1_1_aarch64.whl", hash = "sha256:ab4a0df41e7c16a1392727727e7998a467472d0ad65f3ad5e6e765015df08636"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-musllinux_1_1_i686.whl", hash = "sha256:7ef3cb2ebbf91e330e3bb937efada0edd9003683db6b57bb108c4001f37a02ea"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:0a4e4a1aff6c7ac4cd55792abf96c915634c2b97e3cc1c7129578aa68ebd754e"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-win32.whl", hash = "sha256:fec21693218efe39aa7f8599346e90c705afa52c5b31ae019b2e57e8f6542bb2"}, + {file = "MarkupSafe-2.1.3-cp39-cp39-win_amd64.whl", hash = "sha256:3fd4abcb888d15a94f32b75d8fd18ee162ca0c064f35b11134be77050296d6ba"}, + {file = "MarkupSafe-2.1.3.tar.gz", hash = "sha256:af598ed32d6ae86f1b747b82783958b1a4ab8f617b06fe68795c7f026abbdcad"}, +] + [[package]] name = "maturin" version = "1.2.3" description = "Build and publish crates with pyo3, rust-cpython and cffi bindings as well as rust binaries as python packages" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -150,6 +261,7 @@ zig = ["ziglang (>=0.10.0,<0.11.0)"] name = "mypy" version = "1.1.1" description = "Optional static typing for Python" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -196,6 +308,7 @@ reports = ["lxml"] name = "mypy-extensions" version = "1.0.0" description = "Type system extensions for programs checked with the mypy type checker." +category = "dev" optional = false python-versions = ">=3.5" files = [ @@ -207,6 +320,7 @@ files = [ name = "numpy" version = "1.24.3" description = "Fundamental package for array computing in Python" +category = "main" optional = false python-versions = ">=3.8" files = [ @@ -244,6 +358,7 @@ files = [ name = "packaging" version = "23.0" description = "Core utilities for Python packages" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -255,6 +370,7 @@ files = [ name = "pathspec" version = "0.11.0" description = "Utility library for gitignore style pattern matching of file paths." +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -262,10 +378,32 @@ files = [ {file = "pathspec-0.11.0.tar.gz", hash = "sha256:64d338d4e0914e91c1792321e6907b5a593f1ab1851de7fc269557a21b30ebbc"}, ] +[[package]] +name = "pdoc" +version = "14.1.0" +description = "API Documentation for Python Projects" +category = "dev" +optional = false +python-versions = ">=3.8" +files = [ + {file = "pdoc-14.1.0-py3-none-any.whl", hash = "sha256:e8869dffe21296b3bd5545b28e7f07cae0656082aca43f8915323187e541b126"}, + {file = "pdoc-14.1.0.tar.gz", hash = "sha256:3a0bd921a05c39a82b1505089eb6dc99d857b71b856aa60d1aca4d9086d0e18c"}, +] + +[package.dependencies] +astunparse = {version = "*", markers = "python_version < \"3.9\""} +Jinja2 = ">=2.11.0" +MarkupSafe = "*" +pygments = ">=2.12.0" + +[package.extras] +dev = ["black", "hypothesis", "mypy", "pygments (>=2.14.0)", "pytest", "pytest-cov", "pytest-timeout", "ruff", "tox", "types-pygments"] + [[package]] name = "platformdirs" version = "3.1.1" description = "A small Python package for determining appropriate platform-specific dirs, e.g. a \"user data dir\"." +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -281,6 +419,7 @@ test = ["appdirs (==1.4.4)", "covdefaults (>=2.2.2)", "pytest (>=7.2.1)", "pytes name = "pluggy" version = "1.0.0" description = "plugin and hook calling mechanisms for python" +category = "dev" optional = false python-versions = ">=3.6" files = [ @@ -292,10 +431,26 @@ files = [ dev = ["pre-commit", "tox"] testing = ["pytest", "pytest-benchmark"] +[[package]] +name = "pygments" +version = "2.16.1" +description = "Pygments is a syntax highlighting package written in Python." +category = "dev" +optional = false +python-versions = ">=3.7" +files = [ + {file = "Pygments-2.16.1-py3-none-any.whl", hash = "sha256:13fc09fa63bc8d8671a6d247e1eb303c4b343eaee81d861f3404db2935653692"}, + {file = "Pygments-2.16.1.tar.gz", hash = "sha256:1daff0494820c69bc8941e407aa20f577374ee88364ee10a98fdbe0aece96e29"}, +] + +[package.extras] +plugins = ["importlib-metadata"] + [[package]] name = "pytest" version = "7.2.2" description = "pytest: simple powerful testing with Python" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -315,10 +470,23 @@ tomli = {version = ">=1.0.0", markers = "python_version < \"3.11\""} [package.extras] testing = ["argcomplete", "hypothesis (>=3.56)", "mock", "nose", "pygments (>=2.7.2)", "requests", "xmlschema"] +[[package]] +name = "six" +version = "1.16.0" +description = "Python 2 and 3 compatibility utilities" +category = "dev" +optional = false +python-versions = ">=2.7, !=3.0.*, !=3.1.*, !=3.2.*" +files = [ + {file = "six-1.16.0-py2.py3-none-any.whl", hash = "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254"}, + {file = "six-1.16.0.tar.gz", hash = "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926"}, +] + [[package]] name = "tomli" version = "2.0.1" description = "A lil' TOML parser" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -330,6 +498,7 @@ files = [ name = "typing-extensions" version = "4.5.0" description = "Backported and Experimental Type Hints for Python 3.7+" +category = "dev" optional = false python-versions = ">=3.7" files = [ @@ -337,7 +506,22 @@ files = [ {file = "typing_extensions-4.5.0.tar.gz", hash = "sha256:5cb5f4a79139d699607b3ef622a1dedafa84e115ab0024e0d9c044a9479ca7cb"}, ] +[[package]] +name = "wheel" +version = "0.41.3" +description = "A built-package format for Python" +category = "dev" +optional = false +python-versions = ">=3.7" +files = [ + {file = "wheel-0.41.3-py3-none-any.whl", hash = "sha256:488609bc63a29322326e05560731bf7bfea8e48ad646e1f5e40d366607de0942"}, + {file = "wheel-0.41.3.tar.gz", hash = "sha256:4d4987ce51a49370ea65c0bfd2234e8ce80a12780820d9dc462597a6e60d0841"}, +] + +[package.extras] +test = ["pytest (>=6.0.0)", "setuptools (>=65)"] + [metadata] lock-version = "2.0" python-versions = "^3.8" -content-hash = "078a051e01b6949946a66e742fe8b28b88f97ba5fa7650e161d863dae77cc29f" +content-hash = "c688b8e91c55e759929e2a80f7758c31f1063ebdf1d9098b426c325dbe108511" diff --git a/quil-py/pyproject.toml b/quil-py/pyproject.toml index 50ef7933..acd47c07 100644 --- a/quil-py/pyproject.toml +++ b/quil-py/pyproject.toml @@ -32,6 +32,7 @@ black = "^23.1.0" maturin = "^1.2.3" mypy = "^1.1.1" pytest = "^7.2.2" +pdoc = "^14.1.0" [tool.maturin] features = ["pyo3/extension-module"] diff --git a/quil-py/quil.html b/quil-py/quil.html new file mode 100644 index 00000000..aaa4aa3a --- /dev/null +++ b/quil-py/quil.html @@ -0,0 +1,237 @@ + + + + + + + quil API documentation + + + + + + + + + +
+
+

+quil

+ + + + + + + 
1from .quil import *
+
+ + +
+
+ + \ No newline at end of file diff --git a/quil-py/quil/__init__.py b/quil-py/quil/__init__.py index f6002046..57fb3fa6 100644 --- a/quil-py/quil/__init__.py +++ b/quil-py/quil/__init__.py @@ -1 +1,6 @@ +""" +The `quil` package provides tools for constructing, manipulating, parsing, and printing [Quil](https://github.com/quil-lang/quil) programs. + +⚠️ This package is still in early development and breaking changes should be expected between minor versions. +""" from .quil import * diff --git a/quil-py/quil/expression/__init__.py b/quil-py/quil/expression/__init__.py new file mode 100644 index 00000000..720522e6 --- /dev/null +++ b/quil-py/quil/expression/__init__.py @@ -0,0 +1 @@ +from quil.expression import * diff --git a/quil-py/quil/expression/__init__.pyi b/quil-py/quil/expression/__init__.pyi index 800c8f38..73b6ad4d 100644 --- a/quil-py/quil/expression/__init__.pyi +++ b/quil-py/quil/expression/__init__.pyi @@ -1,3 +1,6 @@ +""" +The ``expression`` module contains classes for representing Quil expressions. +""" from enum import Enum from typing import Dict, final, Sequence, Optional, Union @@ -14,30 +17,30 @@ class Expression: """ A Quil expression. - Variants: - ``address``: An address defined by a ``MemoryReference``. - ``function_call``: A ``FunctionCall``. - ``infix``: An ``InfixExpression``. - ``number``: A number defined as a ``complex``. - ``pi``: The constant `pi`. No inner data. - ``prefix``: A ``PrefixExpression``. - ``variable``: A variable defined as a ``str``. + # Variants: + - ``address``: An address defined by a `quil.instructions.MemoryReference`. + - ``function_call``: A `FunctionCallExpression`. + - ``infix``: An `InfixExpression`. + - ``number``: A number defined as a `complex`. + - ``pi``: The constant ``pi``. No inner data. + - ``prefix``: A `PrefixExpression`. + - ``variable``: A variable defined as a `str`. As seen above, some variants contain inner data that fully specify the expression. For example, the ``number`` variant contains an ``int``. This is in contrast to variants like ``pi`` that have no inner data because they require none to fully specify the expression. This difference is important for determining which methods are available for each variant. - Methods (for each variant): - ``is_*``: Returns ``True`` if the expression is that variant, ``False`` otherwise. + Methods (for every variant): + - ``is_*``: Returns ``True`` if the expression is that variant, ``False`` otherwise. - If the variant has inner data: - ``as_*``: returns the inner data if it is the given variant, ``None`` otherwise. - ``to_*``: returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - ``from_*``: Creates a new ``Expression`` of the given variant from an instance of the inner type. + If the variant has inner data: + - ``as_*``: returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``Expression`` of the given variant from an instance of the inner type. - If the variant doesn't have inner data (e.g. ``pi``) - ``new_*``: Creates a new ``Expression`` for the variant + If the variant doesn't have inner data (e.g. ``pi``) + - ``new_*``: Creates a new ``Expression`` for the variant """ def inner( @@ -113,7 +116,7 @@ class Expression: ... def to_real(self) -> float: """ - If this is a number with imaginary part "equal to" zero (of _small_ absolute value), return + If this is a number with imaginary part "equal to" zero (of small absolute value), return that number. Otherwise, raises an ``EvaluationError`` """ def __add__(self, other: "Expression") -> "Expression": ... @@ -134,6 +137,9 @@ class Expression: """ class FunctionCallExpression: + """ + A Quil function call. + """ @staticmethod def __new__(cls, function: ExpressionFunction, expression: Expression) -> "FunctionCallExpression": ... @property @@ -146,6 +152,9 @@ class FunctionCallExpression: def expression(self, expression: Expression): ... class InfixExpression: + """ + A Quil infix expression. + """ @staticmethod def __new__(cls, left: Expression, operator: InfixOperator, right: Expression): ... @property @@ -162,6 +171,9 @@ class InfixExpression: def right(self, expression: Expression): ... class PrefixExpression: + """ + A Quil prefix expression. + """ @staticmethod def __new__(cls, operator: PrefixOperator, expression: Expression): ... @property @@ -175,6 +187,9 @@ class PrefixExpression: @final class ExpressionFunction(Enum): + """ + An enum representing a Quil function that can be applied to an expression. + """ Cis = "CIS" Cosine = "COSINE" Exponent = "EXPONENT" @@ -183,11 +198,17 @@ class ExpressionFunction(Enum): @final class PrefixOperator(Enum): + """ + An enum that represents the operators supported on a prefix expression. + """ Plus = "PLUS" Minus = "MINUS" @final class InfixOperator(Enum): + """ + An enum that represents the operators supported on an infix expression. + """ Caret = "CARET" Plus = "PLUS" Minus = "MINUS" diff --git a/quil-py/quil/instructions/__init__.py b/quil-py/quil/instructions/__init__.py new file mode 100644 index 00000000..3afbd6db --- /dev/null +++ b/quil-py/quil/instructions/__init__.py @@ -0,0 +1,4 @@ +""" +The `quil.instructions` module contains classes for representing Quil instructions. +""" +from quil.instructions import * diff --git a/quil-py/quil/instructions/__init__.pyi b/quil-py/quil/instructions/__init__.pyi index 8d0c79d1..a16a90ba 100644 --- a/quil-py/quil/instructions/__init__.pyi +++ b/quil-py/quil/instructions/__init__.pyi @@ -11,49 +11,49 @@ class Instruction: """ A Quil instruction. Each variant corresponds to a possible type of Quil instruction. - Variants: - ``arithmetic``: An arithmetic expression defined by an ``Arithmetic``. - ``binary_logic``: A binary expression defined by a ``BinaryLogic``. - ``calibration_definition``: Corresponds to a `DEFCAL` instruction (not `DEFCAL MEASURE`) - defined by a ``Calibration``. - ``capture``: Corresponds to a `CAPTURE` instruction - ``calibration``: Corresponds to a `DEFCAL` instruction. - ``circuit_definition``: Corresponds to a `DEFCIRCUIT` instruction and its body, - defined by a ``CircuitDefinition``. - ``convert``: Corresponds to a `CONVERT` instruction. - ``comparison``: Corresponds to a comparison of two `MemoryReference`s - ``declaration``: Corresponds to a `DECLARE` statement defined by a ``Declaration``. - ``delay``: Corresponds to a `DELAY` instruction. - ``exchange``: Corresponds to an `EXCHANGE` instruction. - ``fence``: Corresponds to a `FENCE` instruction. - ``frame_definition``: Corresponds to a `DEFFRAME` statement, defined by a ``FrameDefinition``. - ``gate``: A Quil quantum gate instruction defined by a ``Gate``. - ``gate_definition``: A quantum gate definition defined by a ``GateDefinition``. - ``halt``: Corresponds to the `HALT` instruction. No inner data. - ``include``: Corresponds to an `INCLUDE` directive. - ``jump``: Corresponds to a `JUMP` instruction - ``jump_when``: Corresponds to a `JUMP-WHEN` instruction - ``jump_unless``: Corresponds to a `JUMP-UNLESS` instruction - ``label``: Corresponds to a `LABEL` - ``load``: Corresponds to a `LOAD` instruction. - ``measure_calibration_definition``: Corresponds to a `DEFCAL MEASURE` instruction. Defined by a ``MeasureCalibrationDefinition``. - ``measurement``: Corresponds to a `MEASURE` instruction. - ``move``: Corresponds to a `MOVE` instruction. - ``nop``: Corresponds to the `NOP` instruction. No inner data. - ``pragma``: Corresponds to a `PRAGMA` instruction. - ``pulse``: Corresponds to a `PULSE` instruction. - ``raw_capture``: Corresponds to a `RAW-CAPTURE` instruction. - ``reset``: Corresponds to a `RESET` instruction. - ``set_frequency``: Corresponds to a `SET-FREQUENCY` instruction. - ``set_phase``: Corresponds to a `SET-PHASE` instruction. - ``set_scale``: Corresponds to a `SET-SCALE` instruction. - ``shift_frequency``: Corresponds to a `SHIFT-FREQUENCY` instruction. - ``shift_phase``: Corresponds to a `SHIFT-PHASE` instruction. - ``store``: Corresponds to a `STORE` instruction. - ``swap_phases``: Corresponds to a `SWAP-PHASES` instruction. - ``unary_logic``: Corresponds to a unary operation on a `MemoryReference`. - ``waveform_definition``: A waveform defined by a ``WaveformDefinition``. - ``wait``: Corresponds to a `WAIT` instruction. No inner data. + # Variants: + - ``arithmetic``: An arithmetic expression defined by an ``Arithmetic``. + - ``binary_logic``: A binary expression defined by a ``BinaryLogic``. + - ``calibration_definition``: Corresponds to a `DEFCAL` instruction (not `DEFCAL MEASURE`) + - defined by a ``Calibration``. + - ``capture``: Corresponds to a `CAPTURE` instruction + - ``calibration``: Corresponds to a `DEFCAL` instruction. + - ``circuit_definition``: Corresponds to a `DEFCIRCUIT` instruction and its body, + - defined by a ``CircuitDefinition``. + - ``convert``: Corresponds to a `CONVERT` instruction. + - ``comparison``: Corresponds to a comparison of two `MemoryReference`s + - ``declaration``: Corresponds to a `DECLARE` statement defined by a ``Declaration``. + - ``delay``: Corresponds to a `DELAY` instruction. + - ``exchange``: Corresponds to an `EXCHANGE` instruction. + - ``fence``: Corresponds to a `FENCE` instruction. + - ``frame_definition``: Corresponds to a `DEFFRAME` statement, defined by a ``FrameDefinition``. + - ``gate``: A Quil quantum gate instruction defined by a ``Gate``. + - ``gate_definition``: A quantum gate definition defined by a ``GateDefinition``. + - ``halt``: Corresponds to the `HALT` instruction. No inner data. + - ``include``: Corresponds to an `INCLUDE` directive. + - ``jump``: Corresponds to a `JUMP` instruction + - ``jump_when``: Corresponds to a `JUMP-WHEN` instruction + - ``jump_unless``: Corresponds to a `JUMP-UNLESS` instruction + - ``label``: Corresponds to a `LABEL` + - ``load``: Corresponds to a `LOAD` instruction. + - ``measure_calibration_definition``: Corresponds to a `DEFCAL MEASURE` instruction. Defined by a ``MeasureCalibrationDefinition``. + - ``measurement``: Corresponds to a `MEASURE` instruction. + - ``move``: Corresponds to a `MOVE` instruction. + - ``nop``: Corresponds to the `NOP` instruction. No inner data. + - ``pragma``: Corresponds to a `PRAGMA` instruction. + - ``pulse``: Corresponds to a `PULSE` instruction. + - ``raw_capture``: Corresponds to a `RAW-CAPTURE` instruction. + - ``reset``: Corresponds to a `RESET` instruction. + - ``set_frequency``: Corresponds to a `SET-FREQUENCY` instruction. + - ``set_phase``: Corresponds to a `SET-PHASE` instruction. + - ``set_scale``: Corresponds to a `SET-SCALE` instruction. + - ``shift_frequency``: Corresponds to a `SHIFT-FREQUENCY` instruction. + - ``shift_phase``: Corresponds to a `SHIFT-PHASE` instruction. + - ``store``: Corresponds to a `STORE` instruction. + - ``swap_phases``: Corresponds to a `SWAP-PHASES` instruction. + - ``unary_logic``: Corresponds to a unary operation on a `MemoryReference`. + - ``waveform_definition``: A waveform defined by a ``WaveformDefinition``. + - ``wait``: Corresponds to a `WAIT` instruction. No inner data. As seen above, some variants contain inner data that fully specify the instruction. For example, the ``gate`` variant contains a ``Gate``. This is in contrast to variants like @@ -61,15 +61,15 @@ class Instruction: This difference is important for determining which methods are available for each variant. Methods (for each variant): - ``is_*``: Returns ``True`` if the instruction is that variant, ``False`` otherwise. + - ``is_*``: Returns ``True`` if the instruction is that variant, ``False`` otherwise. - If the variant has inner data (e.g. ``gate``): - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - ``from_*``: Creates a new ``Instruction`` of the given variant from an instance of the inner type. + If the variant has inner data (e.g. ``gate``): + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``Instruction`` of the given variant from an instance of the inner type. - If the variant doesn't have inner data (e.g. ``halt``) - ``new_*``: Creates a new ``Instruction`` for the variant. + If the variant doesn't have inner data (e.g. ``halt``) + - ``new_*``: Creates a new ``Instruction`` for the variant. """ def __new__( @@ -382,16 +382,16 @@ class ArithmeticOperand: """ A Quil arithmetic operand. - Variants: - ``literal_integer``: An integer literal. - ``literal_real``: A real numbered literal. - ``memory_reference``: A Quil ``MemoryReference``. + # Variants: + - ``literal_integer``: An integer literal. + - ``literal_real``: A real numbered literal. + - ``memory_reference``: A Quil ``MemoryReference``. Methods (for each variant): - ``is_*``: Returns ``True`` if the operand is that variant, ``False`` otherwise. - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - ``from_*``: Creates a new ``ArithmeticOperand`` of the given variant from an instance of the inner type. + - ``is_*``: Returns ``True`` if the operand is that variant, ``False`` otherwise. + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``ArithmeticOperand`` of the given variant from an instance of the inner type. """ def inner(self) -> Union[int, float, MemoryReference]: @@ -486,15 +486,15 @@ class BinaryOperand: """ A Quil binary operand. - Variants: - ``literal_integer``: An integer literal. - ``memory_reference``: A Quil ``MemoryReference``. + # Variants: + - ``literal_integer``: An integer literal. + - ``memory_reference``: A Quil ``MemoryReference``. Methods (for each variant): - ``is_*``: Returns ``True`` if the operand is that variant, ``False`` otherwise. - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - ``from_*``: Creates a new ``BinaryOperand`` of the given variant from an instance of the inner type. + - ``is_*``: Returns ``True`` if the operand is that variant, ``False`` otherwise. + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``BinaryOperand`` of the given variant from an instance of the inner type. """ def inner(self) -> Union[int, MemoryReference]: @@ -671,16 +671,16 @@ class ComparisonOperand: """ A Quil binary operand. - Variants: - ``literal_integer``: An integer literal. - ``literal_real``: A floating point literal. - ``memory_reference``: A Quil ``MemoryReference``. + # Variants: + - ``literal_integer``: An integer literal. + - ``literal_real``: A floating point literal. + - ``memory_reference``: A Quil ``MemoryReference``. Methods (for each variant): - ``is_*``: Returns ``True`` if the operand is that variant, ``False`` otherwise. - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - ``from_*``: Creates a new ``BinaryOperand`` of the given variant from an instance of the inner type. + - ``is_*``: Returns ``True`` if the operand is that variant, ``False`` otherwise. + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``BinaryOperand`` of the given variant from an instance of the inner type. """ def inner(self) -> Union[int, float, MemoryReference]: @@ -1035,16 +1035,15 @@ class AttributeValue: """ A frame attribute value. - Variants: - ``string``: A string attribute containing a ``str``. - ``expression``: An expression attribute containing an ``Expression``. + # Variants: + - ``string``: A string attribute containing a ``str``. + - ``expression``: An expression attribute containing an ``Expression``. Methods (for each variant): - ``is_*``: Returns ``True`` if the ``AttributeValue`` is that variant, ``False`` otherwise. - - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - ``from_*``: Creates a new ``AttributeValue`` of the given variant from an instance of the inner type. + - ``is_*``: Returns ``True`` if the ``AttributeValue`` is that variant, ``False`` otherwise. + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``AttributeValue`` of the given variant from an instance of the inner type. """ def inner(self) -> Union[str, Expression]: @@ -1530,15 +1529,15 @@ class GateSpecification: """ A specification for a gate definition. - Variants: - ``matrix``: A gate specificied by a matrix of ``Expression``s representing a unitary operation. - ``permutation``: A gate specified by a vector of integers that defines a permutation. + # Variants: + - ``matrix``: A gate specificied by a matrix of ``Expression``s representing a unitary operation. + - ``permutation``: A gate specified by a vector of integers that defines a permutation. Methods (for each variant): - - is_*: Returns ``True`` if the inner type is of that variant. - - as_*: Returns the inner data if it is the given variant, ``None`` otherwise. - - to_*: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - - from_*: Creates a new ``GateSpecification`` using an instance of the inner type for the variant. + - is_*: Returns ``True`` if the inner type is of that variant. + - as_*: Returns the inner data if it is the given variant, ``None`` otherwise. + - to_*: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - from_*: Creates a new ``GateSpecification`` using an instance of the inner type for the variant. """ def inner(self) -> Union[List[List[Expression]], List[int], PauliSum]: @@ -1613,15 +1612,15 @@ class Qubit: """ A Qubit - Variants: - ``fixed``: A qubit represented as a fixed integer index. - ``variable``: A qubit represented by a name. + # Variants: + - ``fixed``: A qubit represented as a fixed integer index. + - ``variable``: A qubit represented by a name. Methods (for each variant): - - is_*: Returns ``True`` if the inner type is of that variant. - - as_*: Returns the inner data if it is the given variant, ``None`` otherwise. - - to_*: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - - from_*: Creates a new ``Qubit`` using an instance of the inner type for the variant. + - ``is_*``: Returns ``True`` if the inner type is of that variant. + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``Qubit`` using an instance of the inner type for the variant. """ def inner(self) -> Union[int, str]: @@ -1743,15 +1742,15 @@ class Fence: class PragmaArgument: """ - Variants: - ``identifier``: A Pragma argument defined by a Quil identifier - ``integer``: A Pragma argument defined by an integer + # Variants: + - ``identifier``: A Pragma argument defined by a Quil identifier + - ``integer``: A Pragma argument defined by an integer Methods (for each variant): - - is_*: Returns ``True`` if the inner type is of that variant. - - as_*: Returns the inner data if it is the given variant, ``None`` otherwise. - - to_*: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - - from_*: Creates a new ``PragmaArgument`` using an instance of the inner type for the variant. + - ``is_*``: Returns ``True`` if the inner type is of that variant. + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``PragmaArgument`` using an instance of the inner type for the variant. """ def inner(self) -> Union[str, int]: @@ -2037,15 +2036,15 @@ class Target: """ Represents a Quil target. - Variants: - ``fixed``: A fixed target defined by a Quil identifier - ``placeholder``: A placeholder target that can be assigned a new name at a later time. + # Variants: + - ``fixed``: A fixed target defined by a Quil identifier + - ``placeholder``: A placeholder target that can be assigned a new name at a later time. Methods (for each variant): - - is_*: Returns ``True`` if the inner type is of that variant. - - as_*: Returns the inner data if it is the given variant, ``None`` otherwise. - - to_*: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. - - from_*: Creates a new ``PragmaArgument`` using an instance of the inner type for the variant. + - ``is_*``: Returns ``True`` if the inner type is of that variant. + - ``as_*``: Returns the inner data if it is the given variant, ``None`` otherwise. + - ``to_*``: Returns the inner data if it is the given variant, raises ``ValueError`` otherwise. + - ``from_*``: Creates a new ``PragmaArgument`` using an instance of the inner type for the variant. """ def __new__(cls, inner: Union[str, TargetPlaceholder]) -> "Target": ... diff --git a/quil-py/quil/program/__init__.py b/quil-py/quil/program/__init__.py new file mode 100644 index 00000000..2a4642c3 --- /dev/null +++ b/quil-py/quil/program/__init__.py @@ -0,0 +1,5 @@ +""" +The `quil.program` module contains classes for constructing and representing a +Quil program. +""" +from quil.program import * diff --git a/quil-py/quil/validation/__init__.py b/quil-py/quil/validation/__init__.py new file mode 100644 index 00000000..bec07569 --- /dev/null +++ b/quil-py/quil/validation/__init__.py @@ -0,0 +1,5 @@ +""" +The `quil.validation` module contains classes and functions that can validate +components of a Quil program or instruction. +""" +from quil.validation import * diff --git a/quil-py/quil/validation/identifier.py b/quil-py/quil/validation/identifier.py new file mode 100644 index 00000000..e7271869 --- /dev/null +++ b/quil-py/quil/validation/identifier.py @@ -0,0 +1 @@ +from quil.validation.identifier import *