# Capsula
[](https://pypi.org/project/capsula/)
[](https://anaconda.org/conda-forge/capsula)
[](https://codecov.io/gh/shunichironomura/capsula)
*Capsula*, a Latin word meaning *box*, is a Python package designed to help researchers and developers easily capture and reproduce their command execution context. The primary aim of Capsula is to tackle the reproducibility problem by providing a way to capture the execution context at any point in time, preserving it for future use. This ensures that you can reproduce the exact conditions of past command execution, fostering reproducibility and consistency over time.
Features:
1. **Context Capture:** Capsula logs the details of the execution context for future reference and reproduction. The context includes, but is not limited to, the Python version, system environment variables, and the Git commit hash of the current working directory.
2. **Execution Monitoring:** Capsula monitors the execution of a Python function, logging information such as the execution status, output, duration, etc.
3. **Context Diffing (to be implemented):** Capsula can compare the current context with the context captured at a previous point in time. This is useful for identifying changes or for reproducing the exact conditions of a past execution.
## Usage
Prepare a `capsula.toml` file in the root directory of your project. An example of the `capsula.toml` file is as follows:
```toml
[pre-run]
# Contexts to be captured before the execution of the decorated function/CLI command.
contexts = [
{ type = "CommandContext", command = "poetry check --lock" },
{ type = "CommandContext", command = "pip freeze --exclude-editable > requirements.txt" },
{ type = "FileContext", path = "pyproject.toml", copy = true },
{ type = "FileContext", path = "requirements.txt", move = true },
{ type = "GitRepositoryContext", name = "capsula" },
{ type = "CwdContext" },
{ type = "CpuContext" },
]
# Reporter to be used to report the captured contexts.
reporters = [{ type = "JsonDumpReporter" }]
[in-run]
# Watchers to be used during the execution of the decorated function/CLI command.
watchers = [{ type = "UncaughtExceptionWatcher" }, { type = "TimeWatcher" }]
# Reporter to be used to report the execution status.
reporters = [{ type = "JsonDumpReporter" }]
[post-run]
# Contexts to be captured after the execution of the decorated function/CLI command.
contexts = [{ type = "FileContext", path = "examples/pi.txt", move = true }]
# Reporter to be used to report the captured contexts.
reporters = [{ type = "JsonDumpReporter" }]
```
Then, all you need to do is decorate your Python function with the `@capsula.run` decorator and specify the `load_from_config` argument as `True`. The following is an example of a Python script that estimates the value of π using the Monte Carlo method:
```python
import random
from pathlib import Path
import capsula
@capsula.run(load_from_config=True)
def calculate_pi(n_samples: int = 1_000, seed: int = 42) -> None:
random.seed(seed)
xs = (random.random() for _ in range(n_samples))
ys = (random.random() for _ in range(n_samples))
inside = sum(x * x + y * y <= 1.0 for x, y in zip(xs, ys))
# You can record values to the capsule using the `record` method.
capsula.record("inside", inside)
pi_estimate = (4.0 * inside) / n_samples
print(f"Pi estimate: {pi_estimate}")
capsula.record("pi_estimate", pi_estimate)
print(f"Run name: {capsula.current_run_name()}")
with (Path(__file__).parent / "pi.txt").open("w") as output_file:
output_file.write(f"Pi estimate: {pi_estimate}.")
if __name__ == "__main__":
calculate_pi(n_samples=1_000)
```
<details>
<summary>Example of output <code>pre-run-report.json</code>:</summary>
<pre><code>{
"command": {
"poetry check --lock": {
"command": "poetry check --lock",
"cwd": null,
"returncode": 0,
"stdout": "All set!\n",
"stderr": ""
},
"pip freeze --exclude-editable > requirements.txt": {
"command": "pip freeze --exclude-editable > requirements.txt",
"cwd": null,
"returncode": 0,
"stdout": "",
"stderr": ""
}
},
"file": {
"pyproject.toml": {
"copied_to": [
"vault/calculate_pi_20240225_221901_M7b3/pyproject.toml"
],
"moved_to": null,
"hash": {
"algorithm": "sha256",
"digest": "6c59362587bf43411461b69675980ea338d83a468acddbc8f6cac4f2c17f7605"
}
},
"requirements.txt": {
"copied_to": [],
"moved_to": "vault/calculate_pi_20240225_221901_M7b3",
"hash": {
"algorithm": "sha256",
"digest": "99d0dbddd7f27aa25bd2d7ce3e2f4a555cdb48b039d73a6cf01fc5fa33f527e1"
}
}
},
"git": {
"capsula": {
"working_dir": "/home/nomura/ghq/github.com/shunichironomura/capsula",
"sha": "ff51cb6245e43253d036fcaa0b2af09c0089b783",
"remotes": {
"origin": "ssh://git@github.com/shunichironomura/capsula.git"
},
"branch": "improve-example",
"is_dirty": true
}
},
"cwd": "/home/nomura/ghq/github.com/shunichironomura/capsula",
"cpu": {
"python_version": "3.8.17.final.0 (64 bit)",
"cpuinfo_version": [
9,
0,
0
],
"cpuinfo_version_string": "9.0.0",
"arch": "X86_64",
"bits": 64,
"count": 12,
"arch_string_raw": "x86_64",
"vendor_id_raw": "GenuineIntel",
"brand_raw": "Intel(R) Core(TM) i5-10400 CPU @ 2.90GHz",
"hz_advertised_friendly": "2.9000 GHz",
"hz_actual_friendly": "2.9040 GHz",
"hz_advertised": [
2900000000,
0
],
"hz_actual": [
2904010000,
0
],
"stepping": 5,
"model": 165,
"family": 6,
"flags": [
"3dnowprefetch",
"abm",
"adx",
"aes",
"apic",
"arch_capabilities",
"arch_perfmon",
"avx",
"avx2",
"bmi1",
"bmi2",
"clflush",
"clflushopt",
"cmov",
"constant_tsc",
"cpuid",
"cx16",
"cx8",
"de",
"ept",
"ept_ad",
"erms",
"f16c",
"flush_l1d",
"fma",
"fpu",
"fsgsbase",
"fxsr",
"ht",
"hypervisor",
"ibpb",
"ibrs",
"ibrs_enhanced",
"invpcid",
"invpcid_single",
"lahf_lm",
"lm",
"mca",
"mce",
"mmx",
"movbe",
"msr",
"mtrr",
"nopl",
"nx",
"osxsave",
"pae",
"pat",
"pcid",
"pclmulqdq",
"pdcm",
"pdpe1gb",
"pge",
"pni",
"popcnt",
"pse",
"pse36",
"rdrand",
"rdrnd",
"rdseed",
"rdtscp",
"rep_good",
"sep",
"smap",
"smep",
"ss",
"ssbd",
"sse",
"sse2",
"sse4_1",
"sse4_2",
"ssse3",
"stibp",
"syscall",
"tpr_shadow",
"tsc",
"vme",
"vmx",
"vnmi",
"vpid",
"x2apic",
"xgetbv1",
"xsave",
"xsavec",
"xsaveopt",
"xsaves",
"xtopology"
],
"l3_cache_size": 12582912,
"l2_cache_size": "1.5 MiB",
"l1_data_cache_size": 196608,
"l1_instruction_cache_size": 196608,
"l2_cache_line_size": 256,
"l2_cache_associativity": 6
}
}</code></pre>
</details>
<details>
<summary>Example of output <code>in-run-report.json</code>:</summary>
<pre><code>{
"function": {
"calculate_pi": {
"file_path": "examples/simple_decorator.py",
"first_line_no": 10,
"args": [],
"kwargs": {
"n_samples": 1000
}
}
},
"inside": 782,
"pi_estimate": 3.128,
"exception": {
"exception": {
"exc_type": null,
"exc_value": null,
"traceback": null
}
},
"time": {
"execution_time": "0:00:00.000658"
}
}</code></pre>
</details>
<details>
<summary>Example of output <code>post-run-report.json</code>:</summary>
<pre><code>{
"file": {
"examples/pi.txt": {
"copied_to": [],
"moved_to": "vault/calculate_pi_20240225_221901_M7b3",
"hash": {
"algorithm": "sha256",
"digest": "a64c761cb6b6f9ef1bc1f6afa6ba44d796c5c51d14df0bdc9d3ab9ced7982a74"
}
}
}
}</code></pre>
</details>
## Installation
You can install Capsula via pip:
```bash
pip install capsula
```
Raw data
{
"_id": null,
"home_page": "https://github.com/shunichironomura/capsula",
"name": "capsula",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "reproducibility,cli",
"author": "Shunichiro Nomura",
"author_email": "nomura@space.t.u-tokyo.ac.jp",
"download_url": "https://files.pythonhosted.org/packages/6e/ed/f89fb0504ab42d54b45e06175eedda1ec8413691ebd01a4c8c3762f7a6b4/capsula-0.2.1.tar.gz",
"platform": null,
"description": "# Capsula\n\n[](https://pypi.org/project/capsula/)\n[](https://anaconda.org/conda-forge/capsula)\n\n\n\n[](https://codecov.io/gh/shunichironomura/capsula)\n\n\n*Capsula*, a Latin word meaning *box*, is a Python package designed to help researchers and developers easily capture and reproduce their command execution context. The primary aim of Capsula is to tackle the reproducibility problem by providing a way to capture the execution context at any point in time, preserving it for future use. This ensures that you can reproduce the exact conditions of past command execution, fostering reproducibility and consistency over time.\n\nFeatures:\n\n1. **Context Capture:** Capsula logs the details of the execution context for future reference and reproduction. The context includes, but is not limited to, the Python version, system environment variables, and the Git commit hash of the current working directory.\n\n2. **Execution Monitoring:** Capsula monitors the execution of a Python function, logging information such as the execution status, output, duration, etc.\n\n3. **Context Diffing (to be implemented):** Capsula can compare the current context with the context captured at a previous point in time. This is useful for identifying changes or for reproducing the exact conditions of a past execution.\n\n## Usage\n\nPrepare a `capsula.toml` file in the root directory of your project. An example of the `capsula.toml` file is as follows:\n\n```toml\n[pre-run]\n# Contexts to be captured before the execution of the decorated function/CLI command.\ncontexts = [\n { type = \"CommandContext\", command = \"poetry check --lock\" },\n { type = \"CommandContext\", command = \"pip freeze --exclude-editable > requirements.txt\" },\n { type = \"FileContext\", path = \"pyproject.toml\", copy = true },\n { type = \"FileContext\", path = \"requirements.txt\", move = true },\n { type = \"GitRepositoryContext\", name = \"capsula\" },\n { type = \"CwdContext\" },\n { type = \"CpuContext\" },\n]\n# Reporter to be used to report the captured contexts.\nreporters = [{ type = \"JsonDumpReporter\" }]\n\n[in-run]\n# Watchers to be used during the execution of the decorated function/CLI command.\nwatchers = [{ type = \"UncaughtExceptionWatcher\" }, { type = \"TimeWatcher\" }]\n# Reporter to be used to report the execution status.\nreporters = [{ type = \"JsonDumpReporter\" }]\n\n[post-run]\n# Contexts to be captured after the execution of the decorated function/CLI command.\ncontexts = [{ type = \"FileContext\", path = \"examples/pi.txt\", move = true }]\n# Reporter to be used to report the captured contexts.\nreporters = [{ type = \"JsonDumpReporter\" }]\n```\n\nThen, all you need to do is decorate your Python function with the `@capsula.run` decorator and specify the `load_from_config` argument as `True`. The following is an example of a Python script that estimates the value of \u03c0 using the Monte Carlo method:\n\n```python\nimport random\nfrom pathlib import Path\n\nimport capsula\n\n@capsula.run(load_from_config=True)\ndef calculate_pi(n_samples: int = 1_000, seed: int = 42) -> None:\n random.seed(seed)\n xs = (random.random() for _ in range(n_samples))\n ys = (random.random() for _ in range(n_samples))\n inside = sum(x * x + y * y <= 1.0 for x, y in zip(xs, ys))\n\n # You can record values to the capsule using the `record` method.\n capsula.record(\"inside\", inside)\n\n pi_estimate = (4.0 * inside) / n_samples\n print(f\"Pi estimate: {pi_estimate}\")\n capsula.record(\"pi_estimate\", pi_estimate)\n print(f\"Run name: {capsula.current_run_name()}\")\n\n with (Path(__file__).parent / \"pi.txt\").open(\"w\") as output_file:\n output_file.write(f\"Pi estimate: {pi_estimate}.\")\n\nif __name__ == \"__main__\":\n calculate_pi(n_samples=1_000)\n```\n\n<details>\n<summary>Example of output <code>pre-run-report.json</code>:</summary>\n<pre><code>{\n \"command\": {\n \"poetry check --lock\": {\n \"command\": \"poetry check --lock\",\n \"cwd\": null,\n \"returncode\": 0,\n \"stdout\": \"All set!\\n\",\n \"stderr\": \"\"\n },\n \"pip freeze --exclude-editable > requirements.txt\": {\n \"command\": \"pip freeze --exclude-editable > requirements.txt\",\n \"cwd\": null,\n \"returncode\": 0,\n \"stdout\": \"\",\n \"stderr\": \"\"\n }\n },\n \"file\": {\n \"pyproject.toml\": {\n \"copied_to\": [\n \"vault/calculate_pi_20240225_221901_M7b3/pyproject.toml\"\n ],\n \"moved_to\": null,\n \"hash\": {\n \"algorithm\": \"sha256\",\n \"digest\": \"6c59362587bf43411461b69675980ea338d83a468acddbc8f6cac4f2c17f7605\"\n }\n },\n \"requirements.txt\": {\n \"copied_to\": [],\n \"moved_to\": \"vault/calculate_pi_20240225_221901_M7b3\",\n \"hash\": {\n \"algorithm\": \"sha256\",\n \"digest\": \"99d0dbddd7f27aa25bd2d7ce3e2f4a555cdb48b039d73a6cf01fc5fa33f527e1\"\n }\n }\n },\n \"git\": {\n \"capsula\": {\n \"working_dir\": \"/home/nomura/ghq/github.com/shunichironomura/capsula\",\n \"sha\": \"ff51cb6245e43253d036fcaa0b2af09c0089b783\",\n \"remotes\": {\n \"origin\": \"ssh://git@github.com/shunichironomura/capsula.git\"\n },\n \"branch\": \"improve-example\",\n \"is_dirty\": true\n }\n },\n \"cwd\": \"/home/nomura/ghq/github.com/shunichironomura/capsula\",\n \"cpu\": {\n \"python_version\": \"3.8.17.final.0 (64 bit)\",\n \"cpuinfo_version\": [\n 9,\n 0,\n 0\n ],\n \"cpuinfo_version_string\": \"9.0.0\",\n \"arch\": \"X86_64\",\n \"bits\": 64,\n \"count\": 12,\n \"arch_string_raw\": \"x86_64\",\n \"vendor_id_raw\": \"GenuineIntel\",\n \"brand_raw\": \"Intel(R) Core(TM) i5-10400 CPU @ 2.90GHz\",\n \"hz_advertised_friendly\": \"2.9000 GHz\",\n \"hz_actual_friendly\": \"2.9040 GHz\",\n \"hz_advertised\": [\n 2900000000,\n 0\n ],\n \"hz_actual\": [\n 2904010000,\n 0\n ],\n \"stepping\": 5,\n \"model\": 165,\n \"family\": 6,\n \"flags\": [\n \"3dnowprefetch\",\n \"abm\",\n \"adx\",\n \"aes\",\n \"apic\",\n \"arch_capabilities\",\n \"arch_perfmon\",\n \"avx\",\n \"avx2\",\n \"bmi1\",\n \"bmi2\",\n \"clflush\",\n \"clflushopt\",\n \"cmov\",\n \"constant_tsc\",\n \"cpuid\",\n \"cx16\",\n \"cx8\",\n \"de\",\n \"ept\",\n \"ept_ad\",\n \"erms\",\n \"f16c\",\n \"flush_l1d\",\n \"fma\",\n \"fpu\",\n \"fsgsbase\",\n \"fxsr\",\n \"ht\",\n \"hypervisor\",\n \"ibpb\",\n \"ibrs\",\n \"ibrs_enhanced\",\n \"invpcid\",\n \"invpcid_single\",\n \"lahf_lm\",\n \"lm\",\n \"mca\",\n \"mce\",\n \"mmx\",\n \"movbe\",\n \"msr\",\n \"mtrr\",\n \"nopl\",\n \"nx\",\n \"osxsave\",\n \"pae\",\n \"pat\",\n \"pcid\",\n \"pclmulqdq\",\n \"pdcm\",\n \"pdpe1gb\",\n \"pge\",\n \"pni\",\n \"popcnt\",\n \"pse\",\n \"pse36\",\n \"rdrand\",\n \"rdrnd\",\n \"rdseed\",\n \"rdtscp\",\n \"rep_good\",\n \"sep\",\n \"smap\",\n \"smep\",\n \"ss\",\n \"ssbd\",\n \"sse\",\n \"sse2\",\n \"sse4_1\",\n \"sse4_2\",\n \"ssse3\",\n \"stibp\",\n \"syscall\",\n \"tpr_shadow\",\n \"tsc\",\n \"vme\",\n \"vmx\",\n \"vnmi\",\n \"vpid\",\n \"x2apic\",\n \"xgetbv1\",\n \"xsave\",\n \"xsavec\",\n \"xsaveopt\",\n \"xsaves\",\n \"xtopology\"\n ],\n \"l3_cache_size\": 12582912,\n \"l2_cache_size\": \"1.5 MiB\",\n \"l1_data_cache_size\": 196608,\n \"l1_instruction_cache_size\": 196608,\n \"l2_cache_line_size\": 256,\n \"l2_cache_associativity\": 6\n }\n}</code></pre>\n</details>\n\n<details>\n<summary>Example of output <code>in-run-report.json</code>:</summary>\n<pre><code>{\n \"function\": {\n \"calculate_pi\": {\n \"file_path\": \"examples/simple_decorator.py\",\n \"first_line_no\": 10,\n \"args\": [],\n \"kwargs\": {\n \"n_samples\": 1000\n }\n }\n },\n \"inside\": 782,\n \"pi_estimate\": 3.128,\n \"exception\": {\n \"exception\": {\n \"exc_type\": null,\n \"exc_value\": null,\n \"traceback\": null\n }\n },\n \"time\": {\n \"execution_time\": \"0:00:00.000658\"\n }\n}</code></pre>\n</details>\n\n<details>\n<summary>Example of output <code>post-run-report.json</code>:</summary>\n<pre><code>{\n \"file\": {\n \"examples/pi.txt\": {\n \"copied_to\": [],\n \"moved_to\": \"vault/calculate_pi_20240225_221901_M7b3\",\n \"hash\": {\n \"algorithm\": \"sha256\",\n \"digest\": \"a64c761cb6b6f9ef1bc1f6afa6ba44d796c5c51d14df0bdc9d3ab9ced7982a74\"\n }\n }\n }\n}</code></pre>\n</details>\n\n## Installation\n\nYou can install Capsula via pip:\n\n```bash\npip install capsula\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python package to capture and reproduce command execution context",
"version": "0.2.1",
"project_urls": {
"Homepage": "https://github.com/shunichironomura/capsula",
"Repository": "https://github.com/shunichironomura/capsula"
},
"split_keywords": [
"reproducibility",
"cli"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "543234a696c39f38a790c2b6f00028399e0815c86529eb1cb3a23bb8d628afa9",
"md5": "81801cb46fe915d22d62c8e7c72d0817",
"sha256": "17a7f8c08fc9a94beb24d2e09c42e7a0296bbad527155c5a10f808407e083685"
},
"downloads": -1,
"filename": "capsula-0.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "81801cb46fe915d22d62c8e7c72d0817",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 26896,
"upload_time": "2024-02-26T01:09:41",
"upload_time_iso_8601": "2024-02-26T01:09:41.602631Z",
"url": "https://files.pythonhosted.org/packages/54/32/34a696c39f38a790c2b6f00028399e0815c86529eb1cb3a23bb8d628afa9/capsula-0.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "6eedf89fb0504ab42d54b45e06175eedda1ec8413691ebd01a4c8c3762f7a6b4",
"md5": "20783f854cd03b1b718c6a6ef210c97e",
"sha256": "a094066470849b8e79d8ef4df3a0b69ca14a7ea7f40d1dab56d6774898316a08"
},
"downloads": -1,
"filename": "capsula-0.2.1.tar.gz",
"has_sig": false,
"md5_digest": "20783f854cd03b1b718c6a6ef210c97e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 21174,
"upload_time": "2024-02-26T01:09:43",
"upload_time_iso_8601": "2024-02-26T01:09:43.805020Z",
"url": "https://files.pythonhosted.org/packages/6e/ed/f89fb0504ab42d54b45e06175eedda1ec8413691ebd01a4c8c3762f7a6b4/capsula-0.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 01:09:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shunichironomura",
"github_project": "capsula",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "capsula"
}
JSON
