diff --git a/README.md b/README.md index 6d3d7ca..698b055 100644 --- a/README.md +++ b/README.md @@ -102,14 +102,12 @@ summary_id = job.summary_details["summary_id"] # Retrieve the summary summary = retrieve_summary(summary_id=summary_id) -# Get all information from the retrieved summary -for k, v in summary.__dict__.items(): - print(f"{k}: {v}") - -# Get the summary as one block of text -for k, v in summary.summary.items(): - print(f"Summary Length: {k}") - print(f"Summary: {v['structured_summary'][0].summary}") +# Get the summary as a human-readable string +print(summary.get_formatted_summary()) + +# Save the json object to a file +with open("wordcab_summary.json", "w") as f: + f.write(summary) ``` # Documentation diff --git a/docs/conf.py b/docs/conf.py index c9f1578..fba352c 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,12 +1,31 @@ """Sphinx configuration.""" + +import toml # type: ignore + + +with open("../pyproject.toml") as f: + pyproject = toml.load(f) + project = "Wordcab Python" author = "Wordcab" -copyright = "2022, The Wordcab Team" +copyright = "2022-2023, The Wordcab Team" + +version = pyproject["tool"]["poetry"]["version"] +release = version + +html_title = f"{project} v{version}" +html_last_updated_fmt = "%Y-%m-%d" + extensions = [ "sphinx.ext.autodoc", "sphinx.ext.napoleon", "sphinx_click", + "sphinx_copybutton", "myst_parser", ] + autodoc_typehints = "description" + +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + html_theme = "furo" diff --git a/docs/index.md b/docs/index.md index e99e630..7818af9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -12,12 +12,26 @@ end-before: --- hidden: maxdepth: 2 +caption: Getting Started +name: getting-started --- usage -reference contributing Code of Conduct License Changelog ``` + +```{toctree} +--- +hidden: +maxdepth: 2 +caption: API Reference +name: api-reference +--- + +reference/simple_functions +reference/client +reference/core_objects +``` diff --git a/docs/reference.md b/docs/reference.md deleted file mode 100644 index 145e409..0000000 --- a/docs/reference.md +++ /dev/null @@ -1,207 +0,0 @@ -# Reference - -## Simple functions - -Simple functions are available for all API endpoints. You can use them by importing them from `wordcab`. - -```python ->>> from wordcab import get_stats - ->>> stats = get_stats() ->>> stats -Stats(...) -``` - -They are simple wrappers around the client object. You can use the client object directly if you need more control. - -### get_stats - -```{eval-rst} -.. autofunction:: wordcab.get_stats -``` - -### start_summary - -```{eval-rst} -.. autofunction:: wordcab.start_summary -``` - -### start_extract - -```{eval-rst} -.. autofunction:: wordcab.start_extract -``` - -### list_jobs - -```{eval-rst} -.. autofunction:: wordcab.list_jobs -``` - -### list_summaries - -```{eval-rst} -.. autofunction:: wordcab.list_summaries -``` - -### list_transcripts - -```{eval-rst} -.. autofunction:: wordcab.list_transcripts -``` - -### retrieve_job - -```{eval-rst} -.. autofunction:: wordcab.retrieve_job -``` - -### retrieve_summary - -```{eval-rst} -.. autofunction:: wordcab.retrieve_summary -``` - -### retrieve_transcript - -```{eval-rst} -.. autofunction:: wordcab.retrieve_transcript -``` - -### delete_job - -```{eval-rst} -.. autofunction:: wordcab.delete_job -``` - -### change_speaker_labels - -```{eval-rst} -.. autofunction:: wordcab.change_speaker_labels -``` - -## Client - -The client object is the main interface to the API. You can use it to access all API endpoints. - -```python -from wordcab import Client - -client = Client() -stats = client.get_stats() - -# Run with a context manager -with Client() as client: - stats = client.get_stats() - -# Run with a context manager and a custom API key -with Client(api_key="my_api_key") as client: - stats = client.get_stats() -``` - -```{eval-rst} -.. autoclass:: wordcab.Client - :members: -``` - -## Core objects - -The core objects are used to represent the data returned by the API but also to pass data to the API. - -### Source objects - -#### BaseSource - -```{eval-rst} -.. autoclass:: wordcab.core_objects.BaseSource - :members: -``` - -#### AudioSource - -```{eval-rst} -.. autoclass:: wordcab.core_objects.AudioSource - :members: -``` - -#### GenericSource - -```{eval-rst} -.. autoclass:: wordcab.core_objects.GenericSource - :members: -``` - -#### InMemorySource - -```{eval-rst} -.. autoclass:: wordcab.core_objects.InMemorySource - :members: -``` - -### Job objects - -```{eval-rst} -.. autoclass:: wordcab.core_objects.BaseJob - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.ExtractJob - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.JobSettings - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.ListJobs - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.SummarizeJob - :members: -``` - -### Stats object - -```{eval-rst} -.. autoclass:: wordcab.core_objects.Stats - :members: -``` - -### Summary objects - -```{eval-rst} -.. autoclass:: wordcab.core_objects.BaseSummary - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.ListSummaries - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.StructuredSummary - :members: -``` - -### Transcript objects - -```{eval-rst} -.. autoclass:: wordcab.core_objects.BaseTranscript - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.ListTranscripts - :members: -``` - -```{eval-rst} -.. autoclass:: wordcab.core_objects.TranscriptUtterance - :members: -``` diff --git a/docs/reference/client.md b/docs/reference/client.md new file mode 100644 index 0000000..748eea0 --- /dev/null +++ b/docs/reference/client.md @@ -0,0 +1,23 @@ +# Client + +The client object is the main interface to the API. You can use it to access all API endpoints. + +```python +from wordcab import Client + +client = Client() +stats = client.get_stats() + +# Run with a context manager +with Client() as client: + stats = client.get_stats() + +# Run with a context manager and a custom API key +with Client(api_key="my_api_key") as client: + stats = client.get_stats() +``` + +```{eval-rst} +.. autoclass:: wordcab.Client + :members: +``` diff --git a/docs/reference/core_objects.md b/docs/reference/core_objects.md new file mode 100644 index 0000000..d52dd93 --- /dev/null +++ b/docs/reference/core_objects.md @@ -0,0 +1,143 @@ +# Core objects + +The core objects are used to represent the data returned by the API but also to pass data to the API. + +## Source objects + +### BaseSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.BaseSource + :members: +``` + +### AudioSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.AudioSource + :members: +``` + +### GenericSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.GenericSource + :members: +``` + +### InMemorySource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.InMemorySource + :members: +``` + +### WordcabTranscriptSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.WordcabTranscriptSource + :members: +``` + +### AssemblyAISource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.AssemblyAISource + :members: +``` + +### DeepgramSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.DeepgramSource + :members: +``` + +### RevSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.RevSource + :members: +``` + +### VTTSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.VTTSource + :members: +``` + +### SignedURLSource + +```{eval-rst} +.. autoclass:: wordcab.core_objects.SignedURLSource + :members: +``` + +## Job objects + +```{eval-rst} +.. autoclass:: wordcab.core_objects.BaseJob + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.ExtractJob + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.JobSettings + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.ListJobs + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.SummarizeJob + :members: +``` + +## Stats object + +```{eval-rst} +.. autoclass:: wordcab.core_objects.Stats + :members: +``` + +## Summary objects + +```{eval-rst} +.. autoclass:: wordcab.core_objects.BaseSummary + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.ListSummaries + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.StructuredSummary + :members: +``` + +## Transcript objects + +```{eval-rst} +.. autoclass:: wordcab.core_objects.BaseTranscript + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.ListTranscripts + :members: +``` + +```{eval-rst} +.. autoclass:: wordcab.core_objects.TranscriptUtterance + :members: +``` diff --git a/docs/reference/simple_functions.md b/docs/reference/simple_functions.md new file mode 100644 index 0000000..3998c76 --- /dev/null +++ b/docs/reference/simple_functions.md @@ -0,0 +1,79 @@ +# Simple functions + +Simple functions are available for all API endpoints. You can use them by importing them from `wordcab`. + +```python +>>> from wordcab import get_stats + +>>> stats = get_stats() +>>> stats +Stats(...) +``` + +They are simple wrappers around the client object. You can use the client object directly if you need more control. + +## get_stats + +```{eval-rst} +.. autofunction:: wordcab.get_stats +``` + +## start_summary + +```{eval-rst} +.. autofunction:: wordcab.start_summary +``` + +## start_extract + +```{eval-rst} +.. autofunction:: wordcab.start_extract +``` + +## list_jobs + +```{eval-rst} +.. autofunction:: wordcab.list_jobs +``` + +## list_summaries + +```{eval-rst} +.. autofunction:: wordcab.list_summaries +``` + +## list_transcripts + +```{eval-rst} +.. autofunction:: wordcab.list_transcripts +``` + +## retrieve_job + +```{eval-rst} +.. autofunction:: wordcab.retrieve_job +``` + +## retrieve_summary + +```{eval-rst} +.. autofunction:: wordcab.retrieve_summary +``` + +## retrieve_transcript + +```{eval-rst} +.. autofunction:: wordcab.retrieve_transcript +``` + +## delete_job + +```{eval-rst} +.. autofunction:: wordcab.delete_job +``` + +## change_speaker_labels + +```{eval-rst} +.. autofunction:: wordcab.change_speaker_labels +``` diff --git a/docs/requirements.txt b/docs/requirements.txt index 6513db1..ad13194 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,6 @@ furo==2023.3.23 +myst_parser==1.0.0 sphinx==6.1.3 sphinx-click==4.4.0 -myst_parser==1.0.0 +sphinx-copybutton==0.5.1 +toml==0.10.2 diff --git a/noxfile.py b/noxfile.py index 5f623eb..91cfe94 100644 --- a/noxfile.py +++ b/noxfile.py @@ -228,7 +228,15 @@ def docs(session: Session) -> None: """Build and serve the documentation with live reloading on file changes.""" args = session.posargs or ["--open-browser", "docs", "docs/_build"] session.install(".") - session.install("sphinx", "sphinx-autobuild", "sphinx-click", "furo", "myst-parser") + session.install( + "sphinx", + "sphinx-autobuild", + "sphinx-click", + "sphinx-copybutton", + "furo", + "myst-parser", + "toml", + ) build_dir = Path("docs", "_build") if build_dir.exists(): diff --git a/poetry.lock b/poetry.lock index 8243561..178e999 100644 --- a/poetry.lock +++ b/poetry.lock @@ -2906,6 +2906,25 @@ click = ">=7.0" docutils = "*" sphinx = ">=2.0" +[[package]] +name = "sphinx-copybutton" +version = "0.5.1" +description = "Add a copy button to each of your code cells." +category = "dev" +optional = false +python-versions = ">=3.7" +files = [ + {file = "sphinx-copybutton-0.5.1.tar.gz", hash = "sha256:366251e28a6f6041514bfb5439425210418d6c750e98d3a695b73e56866a677a"}, + {file = "sphinx_copybutton-0.5.1-py3-none-any.whl", hash = "sha256:0842851b5955087a7ec7fc870b622cb168618ad408dee42692e9a5c97d071da8"}, +] + +[package.dependencies] +sphinx = ">=1.8" + +[package.extras] +code-style = ["pre-commit (==2.12.1)"] +rtd = ["ipython", "myst-nb", "sphinx", "sphinx-book-theme", "sphinx-examples"] + [[package]] name = "sphinxcontrib-applehelp" version = "1.0.4" @@ -3345,4 +3364,4 @@ testing = ["big-O", "flake8 (<5)", "jaraco.functools", "jaraco.itertools", "more [metadata] lock-version = "2.0" python-versions = ">=3.8,<4.0" -content-hash = "833399a31329d29cba059fd052d2cdfb90cad432500f130ee2d989591f663f34" +content-hash = "e89e6015a9f48ab373a28bc003d3119ac4dc4696dc9a063c88fd0730747c71b4" diff --git a/pyproject.toml b/pyproject.toml index b97d2fc..dc1aa69 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,6 +50,8 @@ safety = ">=1.10.3" sphinx = ">=4.3.2" sphinx-autobuild = ">=2021.3.14" sphinx-click = ">=3.0.2" +sphinx-copybutton = ">=0.5.1" +toml = ">=0.10.2" # typeguard = ">=2.13.3" # Deactivated due to runtime errors with Client class xdoctest = {extras = ["colors"], version = ">=0.15.10"} diff --git a/src/wordcab/core_objects/source.py b/src/wordcab/core_objects/source.py index 8954e0f..2a5036d 100644 --- a/src/wordcab/core_objects/source.py +++ b/src/wordcab/core_objects/source.py @@ -451,7 +451,36 @@ def __post_init__(self) -> None: @dataclass class AssemblyAISource(BaseSource): - """AssemblyAI source object.""" + """ + AssemblyAI source object using a local or remote AssemblyAI JSON file. + + Parameters + ---------- + filepath : Union[str, Path] + The path to the local file. + url : str + The URL to the remote file. + + Raises + ------ + ValueError + If the file format is not valid. + + Examples + -------- + >>> from wordcab.core_objects import AssemblyAISource + + >>> assemblyai_source = AssemblyAISource(filepath="path/to/assemblyai/file.json") # doctest: +SKIP + >>> assemblyai_source # doctest: +SKIP + AssemblyAISource(...) + >>> assemblyai_source.source # doctest: +SKIP + 'assembly_ai' + + Returns + ------- + AssemblyAISource + The AssemblyAI source object. + """ def __post_init__(self) -> None: """Post-init method.""" @@ -486,7 +515,36 @@ def prepare_headers(self) -> Dict[str, str]: @dataclass class DeepgramSource(BaseSource): - """Deepgram source object.""" + """ + Deepgram source object using a local or remote Deepgram JSON file. + + Parameters + ---------- + filepath : Union[str, Path] + The path to the local file. + url : str + The URL to the remote file. + + Raises + ------ + ValueError + If the file format is not valid. + + Examples + -------- + >>> from wordcab.core_objects import DeepgramSource + + >>> deepgram_source = DeepgramSource(filepath="path/to/deepgram/file.json") # doctest: +SKIP + >>> deepgram_source # doctest: +SKIP + DeepgramSource(...) + >>> deepgram_source.source # doctest: +SKIP + 'deepgram' + + Returns + ------- + DeepgramSource + The Deepgram source object. + """ def __post_init__(self) -> None: """Post-init method.""" @@ -521,7 +579,36 @@ def prepare_headers(self) -> Dict[str, str]: @dataclass class RevSource(BaseSource): - """Rev.ai source object.""" + """ + Rev.ai source object using a local or remote Rev.ai JSON file. + + Parameters + ---------- + filepath : Union[str, Path] + The path to the local file. + url : str + The URL to the remote file. + + Raises + ------ + ValueError + If the file format is not valid. + + Examples + -------- + >>> from wordcab.core_objects import RevSource + + >>> rev_source = RevSource(filepath="path/to/rev/file.json") # doctest: +SKIP + >>> rev_source # doctest: +SKIP + RevSource(...) + >>> rev_source.source # doctest: +SKIP + 'rev_ai' + + Returns + ------- + RevSource + The Rev.ai source object. + """ def __post_init__(self) -> None: """Post-init method.""" @@ -554,7 +641,36 @@ def prepare_headers(self) -> Dict[str, str]: @dataclass class VTTSource(BaseSource): - """VTT source object.""" + """ + VTT source object using a local or remote VTT file. + + Parameters + ---------- + filepath : Union[str, Path] + The path to the local file. + url : str + The URL to the remote file. + + Raises + ------ + ValueError + If the file format is not valid. + + Examples + -------- + >>> from wordcab.core_objects import VTTSource + + >>> vtt_source = VTTSource(filepath="path/to/vtt/file.vtt") # doctest: +SKIP + >>> vtt_source # doctest: +SKIP + VTTSource(...) + >>> vtt_source.source # doctest: +SKIP + 'vtt' + + Returns + ------- + VTTSource + The VTT source object. + """ filename: str = field(init=False)