# Touca Python SDK
[](https://pypi.org/project/touca/)
[](https://github.com/trytouca/trytouca/blob/main/sdk/python/LICENSE)
[](https://pypi.org/project/touca)
[](https://github.com/trytouca/trytouca/actions/workflows/build.yml?query=branch:main+event:push)
[](https://touca-python.readthedocs.io)
[](https://app.codecov.io/gh/trytouca/trytouca)
## Install
```bash
pip install touca
```
We support Python v3.6 and newer.
## Sneak Peak
> For a more thorough guide of how to use Touca SDK for Python, refer to our
> [documentation website](https://touca.io/docs).
Let us imagine that we want to test a software workflow that takes the username
of a student and provides basic information about them.
```py
def test_find_student():
alice = find_student("alice")
assert alice.fullname == "Alice Anderson"
assert alice.dob == date(2006, 3, 1)
assert alice.gpa == 3.9
```
We can use unit testing in which we hard-code expected values for each input.
But real-world software is complex:
- We need a large number of test inputs to gain confidence that our software
works as expected.
- Describing the expected behavior of our software for each test input is
difficult.
- When we make intentional changes to the behavior of our software, updating our
expected values is cumbersome.
Touca is effective in testing software workflows that need to handle a large
variety of inputs or whose expected behavior is difficult to hard-code.
```py
import touca
from students import find_student
@touca.workflow(testcases=["alice", "bob", "charlie"])
def students_test(username: str):
student = find_student(username)
touca.check("fullname", student.fullname)
touca.check("dob", student.dob)
touca.check("gpa", student.gpa)
```
This is slightly different from a typical unit test:
- Touca tests do not use expected values.
- Touca tests do not hard-code input values.
With Touca, we describe how we run our code under test for any given test case.
We can capture values of interesting variables and runtime of important
functions to describe the behavior and performance of our workflow for that test
case.
Now if we make changes to our workflow under test, we can rerun this test and
let Touca automatically compare our captured data points against those of a
previous baseline version and report any difference in behavior or performance.
## Documentation
- [Documentation Website](https://touca.io/docs): If you are new to Touca, this
is the best place to start.
- [Python SDK API Reference](https://touca.io/docs/external/sdk/python/index.html):
Auto-generated source code documentation for Touca Python SDK with explanation
about individual API functions.
- [Python Examples](https://github.com/trytouca/trytouca/tree/main/examples/python):
Sample Python projects that show how to use Touca in various real-world
use-cases.
## Community
We hang on [Discord](https://touca.io/discord). Come say hi! We love making new
friends. If you need help, have any questions, or like to contribute or provide
feedback, that's the best place to be.
## Contributing
We welcome all forms of contributions, from adding new features to improving
documentation and sharing feedback.
- [Code of Conduct](https://touca.io/docs/contributing/conduct/)
- [Contributing Guide](https://touca.io/docs/contributing/)
- [Good First Issues](https://touca.io/docs/contributing/good-first-issues/)
## FAQ
- Should I install Touca as a development dependency?
Yes, unless you like to capture data-points that are not accessible through
your software's public API. Touca data capturing functions (e.g. `touca.check`
and `touca.scoped_timer`) are no-op in production environments. They only work
when called from a `@touca.workflow` context.
- How is Touca making money?
Touca is open-source software that you can self-host for free. Touca, Inc.
operates [Touca Cloud](https://app.touca.io): a managed cloud instance of
Touca with additional enterprise-ready features. We have a free plan and
leverage usage-based pricing to charge for storage and service. Visit our
[pricing page](https://touca.io/pricing) to learn more.
## License
This repository is released under the Apache-2.0 License. See
[`LICENSE`](https://github.com/trytouca/trytouca/blob/main/sdk/python/LICENSE).
Raw data
{
"_id": null,
"home_page": "https://github.com/trytouca/trytouca/tree/main/sdk/python",
"name": "touca",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "touca,snapshot testing,regression testing",
"author": "Touca, Inc.",
"author_email": "support@touca.io",
"download_url": "https://files.pythonhosted.org/packages/ef/d7/c19d5cc50d56ace8bdbb70ab17611b970f231208889c1eda7257cc5e8a54/touca-1.8.5.tar.gz",
"platform": null,
"description": "# Touca Python SDK\n\n[](https://pypi.org/project/touca/)\n[](https://github.com/trytouca/trytouca/blob/main/sdk/python/LICENSE)\n[](https://pypi.org/project/touca)\n[](https://github.com/trytouca/trytouca/actions/workflows/build.yml?query=branch:main+event:push)\n[](https://touca-python.readthedocs.io)\n[](https://app.codecov.io/gh/trytouca/trytouca)\n\n## Install\n\n```bash\npip install touca\n```\n\nWe support Python v3.6 and newer.\n\n## Sneak Peak\n\n> For a more thorough guide of how to use Touca SDK for Python, refer to our\n> [documentation website](https://touca.io/docs).\n\nLet us imagine that we want to test a software workflow that takes the username\nof a student and provides basic information about them.\n\n```py\ndef test_find_student():\n alice = find_student(\"alice\")\n assert alice.fullname == \"Alice Anderson\"\n assert alice.dob == date(2006, 3, 1)\n assert alice.gpa == 3.9\n```\n\nWe can use unit testing in which we hard-code expected values for each input.\nBut real-world software is complex:\n\n- We need a large number of test inputs to gain confidence that our software\n works as expected.\n- Describing the expected behavior of our software for each test input is\n difficult.\n- When we make intentional changes to the behavior of our software, updating our\n expected values is cumbersome.\n\nTouca is effective in testing software workflows that need to handle a large\nvariety of inputs or whose expected behavior is difficult to hard-code.\n\n```py\nimport touca\nfrom students import find_student\n\n@touca.workflow(testcases=[\"alice\", \"bob\", \"charlie\"])\ndef students_test(username: str):\n student = find_student(username)\n touca.check(\"fullname\", student.fullname)\n touca.check(\"dob\", student.dob)\n touca.check(\"gpa\", student.gpa)\n```\n\nThis is slightly different from a typical unit test:\n\n- Touca tests do not use expected values.\n- Touca tests do not hard-code input values.\n\nWith Touca, we describe how we run our code under test for any given test case.\nWe can capture values of interesting variables and runtime of important\nfunctions to describe the behavior and performance of our workflow for that test\ncase.\n\n\n\nNow if we make changes to our workflow under test, we can rerun this test and\nlet Touca automatically compare our captured data points against those of a\nprevious baseline version and report any difference in behavior or performance.\n\n## Documentation\n\n- [Documentation Website](https://touca.io/docs): If you are new to Touca, this\n is the best place to start.\n- [Python SDK API Reference](https://touca.io/docs/external/sdk/python/index.html):\n Auto-generated source code documentation for Touca Python SDK with explanation\n about individual API functions.\n- [Python Examples](https://github.com/trytouca/trytouca/tree/main/examples/python):\n Sample Python projects that show how to use Touca in various real-world\n use-cases.\n\n## Community\n\nWe hang on [Discord](https://touca.io/discord). Come say hi! We love making new\nfriends. If you need help, have any questions, or like to contribute or provide\nfeedback, that's the best place to be.\n\n## Contributing\n\nWe welcome all forms of contributions, from adding new features to improving\ndocumentation and sharing feedback.\n\n- [Code of Conduct](https://touca.io/docs/contributing/conduct/)\n- [Contributing Guide](https://touca.io/docs/contributing/)\n- [Good First Issues](https://touca.io/docs/contributing/good-first-issues/)\n\n## FAQ\n\n- Should I install Touca as a development dependency?\n\n Yes, unless you like to capture data-points that are not accessible through\n your software's public API. Touca data capturing functions (e.g. `touca.check`\n and `touca.scoped_timer`) are no-op in production environments. They only work\n when called from a `@touca.workflow` context.\n\n- How is Touca making money?\n\n Touca is open-source software that you can self-host for free. Touca, Inc.\n operates [Touca Cloud](https://app.touca.io): a managed cloud instance of\n Touca with additional enterprise-ready features. We have a free plan and\n leverage usage-based pricing to charge for storage and service. Visit our\n [pricing page](https://touca.io/pricing) to learn more.\n\n## License\n\nThis repository is released under the Apache-2.0 License. See\n[`LICENSE`](https://github.com/trytouca/trytouca/blob/main/sdk/python/LICENSE).\n\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Touca SDK for Python",
"version": "1.8.5",
"split_keywords": [
"touca",
"snapshot testing",
"regression testing"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "06d2d2014d778c26259daf50a3e0a5d21b7e72694c1e22037cf781ed8e76daf1",
"md5": "9b16bffb9e84eb16a543d8e53cedd1f8",
"sha256": "c2da933ff3badeb2d3162269a46c70f5427b985bee13b0201941deff46e485a7"
},
"downloads": -1,
"filename": "touca-1.8.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9b16bffb9e84eb16a543d8e53cedd1f8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 55318,
"upload_time": "2023-01-31T02:49:29",
"upload_time_iso_8601": "2023-01-31T02:49:29.602433Z",
"url": "https://files.pythonhosted.org/packages/06/d2/d2014d778c26259daf50a3e0a5d21b7e72694c1e22037cf781ed8e76daf1/touca-1.8.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "efd7c19d5cc50d56ace8bdbb70ab17611b970f231208889c1eda7257cc5e8a54",
"md5": "ab4d6188c8dd3d2f4f9ab90575829989",
"sha256": "60462cbfb2b74a1be0fa8370acdd1f53d1ff3f2fde353a053fea0d6ecbc88277"
},
"downloads": -1,
"filename": "touca-1.8.5.tar.gz",
"has_sig": false,
"md5_digest": "ab4d6188c8dd3d2f4f9ab90575829989",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 43511,
"upload_time": "2023-01-31T02:49:31",
"upload_time_iso_8601": "2023-01-31T02:49:31.240045Z",
"url": "https://files.pythonhosted.org/packages/ef/d7/c19d5cc50d56ace8bdbb70ab17611b970f231208889c1eda7257cc5e8a54/touca-1.8.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-31 02:49:31",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "touca"
}
JSON