Skip to content

Commit 378c7e7

Browse files
AbstractUmbraAbstractUmbra
committed
add docs
1 parent 68b369f commit 378c7e7

File tree

5 files changed

+232
-81
lines changed

5 files changed

+232
-81
lines changed

‎docs/conf.py

Lines changed: 67 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -15,19 +15,44 @@
1515
import sys
1616

1717

18-
sys.path.insert(0, os.path.abspath(".."))
18+
# from typing import Literal, Optional
19+
20+
21+
_DISCORD: str = "https://discord.gg/RAKc3HF"
22+
_DISCORD_SVG: str = """
23+
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16" height="1em" width="1em" xmlns="http://www.w3.org/2000/svg">
24+
<path d="M6.552 6.712c-.456 0-.816.4-.816.888s.368.888.816.888c.456 0 .816-.4.816-.888.008-.488-.36-.888-.816-.888zm2.92 0c-.456 0-.816.4-.816.888s.368.888.816.888c.456 0 .816-.4.816-.888s-.36-.888-.816-.888z"></path>
25+
<path d="M13.36 0H2.64C1.736 0 1 .736 1 1.648v10.816c0 .912.736 1.648 1.64 1.648h9.072l-.424-1.48 1.024.952.968.896L15 16V1.648C15 .736 14.264 0 13.36 0zm-3.088 10.448s-.288-.344-.528-.648c1.048-.296 1.448-.952 1.448-.952-.328.216-.64.368-.92.472-.4.168-.784.28-1.16.344a5.604 5.604 0 0 1-2.072-.008 6.716 6.716 0 0 1-1.176-.344 4.688 4.688 0 0 1-.584-.272c-.024-.016-.048-.024-.072-.04-.016-.008-.024-.016-.032-.024-.144-.08-.224-.136-.224-.136s.384.64 1.4.944c-.24.304-.536.664-.536.664-1.768-.056-2.44-1.216-2.44-1.216 0-2.576 1.152-4.664 1.152-4.664 1.152-.864 2.248-.84 2.248-.84l.08.096c-1.44.416-2.104 1.048-2.104 1.048s.176-.096.472-.232c.856-.376 1.536-.48 1.816-.504.048-.008.088-.016.136-.016a6.521 6.521 0 0 1 4.024.752s-.632-.6-1.992-1.016l.112-.128s1.096-.024 2.248.84c0 0 1.152 2.088 1.152 4.664 0 0-.68 1.16-2.448 1.216z"></path>
26+
</svg>
27+
"""
28+
29+
_GITHUB: str = "https://github.com/PythonistaGuild/mystbin.py"
30+
_GITHUB_SVG: str = """
31+
<svg stroke="currentColor" fill="currentColor" stroke-width="0" viewBox="0 0 16 16">
32+
<path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0 0 16 8c0-4.42-3.58-8-8-8z"></path>
33+
</svg>
34+
"""
35+
36+
_RTD: str = "https://readthedocs.io/"
37+
_RTD_SVG: str = """
38+
<svg x="0px" y="0px" viewBox="-125 217 360 360" xml:space="preserve">
39+
<path fill="currentColor" d="M39.2,391.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3 c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2 c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,391.3,40.4,391.1,39.2,391.3z M39.2,353.6c-4.2,0.6-7.1,4.4-6.5,8.5 c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4 c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,353.6,40.4,353.4,39.2,353.6z M39.2,315.9 c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8 c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6c-30.1-2.4-46.5-7.9-46.5-7.9 C41.7,315.9,40.4,315.8,39.2,315.9z M39.2,278.3c-4.2,0.6-7.1,4.4-6.5,8.5c0.4,3,2.6,5.5,5.5,6.3c0,0,18.5,6.1,50,8.7 c25.3,2.1,54-1.8,54-1.8c4.2-0.1,7.5-3.6,7.4-7.8c-0.1-4.2-3.6-7.5-7.8-7.4c-0.5,0-1,0.1-1.5,0.2c0,0-28.1,3.5-50.9,1.6 c-30.1-2.4-46.5-7.9-46.5-7.9C41.7,278.2,40.4,278.1,39.2,278.3z M-13.6,238.5c-39.6,0.3-54.3,12.5-54.3,12.5v295.7 c0,0,14.4-12.4,60.8-10.5s55.9,18.2,112.9,19.3s71.3-8.8,71.3-8.8l0.8-301.4c0,0-25.6,7.3-75.6,7.7c-49.9,0.4-61.9-12.7-107.7-14.2 C-8.2,238.6-10.9,238.5-13.6,238.5z M19.5,257.8c0,0,24,7.9,68.3,10.1c37.5,1.9,75-3.7,75-3.7v267.9c0,0-19,10-66.5,6.6 C59.5,536.1,19,522.1,19,522.1L19.5,257.8z M-3.6,264.8c4.2,0,7.7,3.4,7.7,7.7c0,4.2-3.4,7.7-7.7,7.7c0,0-12.4,0.1-20,0.8 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,0,0,0,0c0,0,11.3-6,27-7.5 C-16,264.9-3.6,264.8-3.6,264.8z M-11,302.6c4.2-0.1,7.4,0,7.4,0c4.2,0.5,7.2,4.3,6.7,8.5c-0.4,3.5-3.2,6.3-6.7,6.7 c0,0-12.4,0.1-20,0.8c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5 C-20.5,302.9-15.2,302.7-11,302.6z M-3.6,340.2c4.2,0,7.7,3.4,7.7,7.7s-3.4,7.7-7.7,7.7c0,0-12.4-0.1-20,0.7 c-12.7,1.3-21.4,5.9-21.4,5.9c-3.7,2-8.4,0.5-10.3-3.2c-2-3.7-0.5-8.4,3.2-10.3c0,0,11.3-6,27-7.5C-16,340.1-3.6,340.2-3.6,340.2z"></path>
40+
</svg>
41+
"""
1942

2043
# -- Project information -----------------------------------------------------
2144

22-
project = "Mystbin"
23-
copyright = "2021, Alex Nørgaard"
24-
author = "Alex Nørgaard"
45+
project: str = "Mystbin"
46+
copyright: str = "2020 - Present, Alex Nørgaard"
47+
author: str = "Alex Nørgaard"
2548

2649
# The full version, including alpha/beta/rc tags
27-
version = ""
28-
2950
with open("../mystbin/__init__.py") as f:
30-
version = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]', f.read(), re.MULTILINE).group(1)
51+
match = re.search(r'^__version__\s*=\s*[\'"]([^\'"]*)[\'"]', f.read(), re.MULTILINE)
52+
if match is not None:
53+
version = match.group(1)
54+
else:
55+
version = ""
3156

3257
release = version
3358

@@ -37,33 +62,45 @@
3762
# Add any Sphinx extension module names here, as strings. They can be
3863
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
3964
# ones.
40-
extensions = [
65+
sys.path.insert(0, os.path.abspath(".."))
66+
sys.path.append(os.path.abspath("extensions"))
67+
68+
extensions: list[str] = [
4169
"sphinx.ext.autodoc",
4270
"sphinx.ext.extlinks",
4371
"sphinx.ext.intersphinx",
4472
"sphinx.ext.napoleon",
73+
"sphinx.ext.viewcode",
4574
"sphinxcontrib_trio",
4675
]
4776

77+
extlinks: dict[str, tuple[str, str]] = {"issue": (f"{_GITHUB}/issues/%s", "GH-%s")}
78+
4879
# Add any paths that contain templates here, relative to this directory.
49-
templates_path = ["_templates"]
80+
templates_path: list[str] = ["_templates"]
5081

51-
autodoc_typehints = "none"
82+
autodoc_typehints: str = "both"
83+
autodoc_typehints_format: str = "short"
84+
autodoc_typehints_description_target: str = "documented"
85+
autodoc_member_order: str = "bysource"
86+
autodoc_preserve_defaults: bool = False
87+
napoleon_use_admonition_for_examples: bool = True
88+
napoleon_use_admonition_for_notes: bool = True
5289

5390
# List of patterns, relative to source directory, that match files and
5491
# directories to ignore when looking for source files.
5592
# This pattern also affects html_static_path and html_extra_path.
56-
exclude_patterns = ["build", "Thumbs.db", ".DS_Store"]
93+
exclude_patterns: list[str] = ["build", "Thumbs.db", ".DS_Store"]
5794

5895
# Links used for cross-referencing other documentation
59-
intersphinx_mapping = {
60-
"py": ("https://docs.python.org/3", None),
61-
"aio": ("https://docs.aiohttp.org/en/stable/", None),
62-
"req": ("https://requests.readthedocs.io/en/latest/", None),
96+
intersphinx_mapping: dict[str, tuple[str, None]] = {
97+
"python": ("https://docs.python.org/3", None),
98+
"aiohttp": ("https://docs.aiohttp.org/en/stable/", None),
99+
"requests": ("https://requests.readthedocs.io/en/latest/", None),
63100
}
64101

65102
# Prolog for asynchronous functions
66-
rst_prolog = """
103+
rst_prolog: str = """
67104
.. |coro| replace:: This function is a |coroutine_link|_.
68105
.. |maybecoro| replace:: This function *could be a* |coroutine_link|_.
69106
.. |coroutine_link| replace:: *coroutine*
@@ -75,9 +112,18 @@
75112
# The theme to use for HTML and HTML Help pages. See the documentation for
76113
# a list of builtin themes.
77114
#
78-
html_theme = "furo"
115+
html_theme: str = "furo"
116+
html_theme_options: dict[str, list[dict[str, str]]] = {
117+
"footer_icons": [
118+
{"name": "Discord", "url": _DISCORD, "html": _DISCORD_SVG, "class": ""},
119+
{"name": "Github", "url": _GITHUB, "html": _GITHUB_SVG, "class": ""},
120+
{"name": "readthedocs.io", "url": _RTD, "html": _RTD_SVG, "class": ""},
121+
],
122+
}
79123

80-
# Add any paths that contain custom static files (such as style sheets) here,
81-
# relative to this directory. They are copied after the builtin static files,
82-
# so a file named "default.css" will overwrite the builtin "default.css".
83-
html_static_path = ["_static"]
124+
resource_links: dict[str, str] = {
125+
"github": _GITHUB,
126+
"issues": f"{_GITHUB}/issues",
127+
"discussions": f"{_GITHUB}/discussions",
128+
"discord": _DISCORD,
129+
}

‎mystbin/client.py

Lines changed: 136 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,13 @@
2323
from __future__ import annotations
2424

2525
import datetime
26-
from typing import Optional, overload
26+
from typing import Optional
2727

2828
import aiohttp
2929

3030
from .http import HTTPClient
3131
from .paste import File, Paste
32-
from .utils import MISSING, require_authentication
32+
from .utils import require_authentication
3333

3434

3535
__all__ = ("Client",)
@@ -50,77 +50,160 @@ async def create_paste(
5050
password: Optional[str] = None,
5151
expires: Optional[datetime.datetime] = None,
5252
) -> Paste:
53+
"""|coro|
54+
55+
Create a single file paste on mystb.in.
56+
57+
Parameters
58+
-----------
59+
filename: :class:`str`
60+
The filename to create.
61+
content: :class:`str`
62+
The content of the file you are creating.
63+
syntax: Optional[:class:`str`]
64+
The syntax of the file to create, if any.
65+
password: Optional[:class:`str`]
66+
The password of the paste, if any.
67+
expires: Optional[:class:`datetime.datetime`]
68+
When the paste expires, if any.
69+
70+
Returns
71+
--------
72+
:class:`mystbin.Paste`
73+
The paste that was created.
74+
"""
5375
file = File(filename=filename, content=content, syntax=syntax)
5476
data = await self.http._create_paste(file=file, password=password, expires=expires)
55-
return Paste.from_data(data)
77+
return Paste._from_data(data)
5678

5779
async def create_multifile_paste(
5880
self, *, files: list[File], password: Optional[str] = None, expires: Optional[datetime.datetime] = None
5981
) -> Paste:
82+
"""|coro|
83+
84+
Create a paste with multiple files on mystb.in.
85+
86+
Parameters
87+
------------
88+
files: list[:class:`mystbin.File`]
89+
A list of files to create on mystbin.
90+
password: Optional[:class:`str`]
91+
The password for this paste, if any.
92+
expires: Optional[:class:`datetime.datetime`]
93+
When this paste expires, if any.
94+
95+
Returns
96+
--------
97+
:class:`mystbin.Paste`
98+
The paste that was created.
99+
"""
60100
data = await self.http._create_paste(files=files, password=password, expires=expires)
61-
return Paste.from_data(data)
101+
return Paste._from_data(data)
62102

63103
@require_authentication
64104
async def delete_paste(self, paste_id: str, /) -> None:
105+
"""|coro|
106+
107+
Delete a paste.
108+
109+
Parameters
110+
-----------
111+
paste_id: :class:`str`
112+
The paste to delete.
113+
"""
65114
await self.http._delete_pastes(paste_ids=[paste_id])
66115

67116
@require_authentication
68117
async def delete_pastes(self, paste_ids: list[str], /) -> None:
118+
"""|coro|
119+
120+
Delete multiple pastes.
121+
122+
Parameters
123+
-----------
124+
paste_ids: list[:class:`str`]
125+
The pastes to delete.
126+
"""
69127
await self.http._delete_pastes(paste_ids=paste_ids)
70128

71129
async def get_paste(self, paste_id: str, *, password: Optional[str] = None) -> Paste:
72-
data = await self.http._get_paste(paste_id=paste_id, password=password)
73-
return Paste.from_data(data)
74-
75-
@overload
76-
async def edit_paste(self, paste_id: str, *, new_content: str, new_filename: ..., new_expires: ...) -> None:
77-
...
78-
79-
@overload
80-
async def edit_paste(self, paste_id: str, *, new_content: ..., new_filename: str, new_expires: ...) -> None:
81-
...
82-
83-
@overload
84-
async def edit_paste(
85-
self, paste_id: str, *, new_content: ..., new_filename: ..., new_expires: datetime.datetime
86-
) -> None:
87-
...
88-
89-
@overload
90-
async def edit_paste(self, paste_id: str, *, new_content: str, new_filename: str, new_expires: ...) -> None:
91-
...
92-
93-
@overload
94-
async def edit_paste(
95-
self, paste_id: str, *, new_content: str, new_filename: ..., new_expires: datetime.datetime
96-
) -> None:
97-
...
98-
99-
@overload
100-
async def edit_paste(
101-
self, paste_id: str, *, new_content: ..., new_filename: str, new_expires: datetime.datetime
102-
) -> None:
103-
...
104-
105-
@overload
106-
async def edit_paste(
107-
self, paste_id: str, *, new_content: str, new_filename: str, new_expires: datetime.datetime
108-
) -> None:
109-
...
130+
"""|coro|
110131
111-
@require_authentication
112-
async def edit_paste(
113-
self,
114-
paste_id: str,
115-
*,
116-
new_content: Optional[str] = MISSING,
117-
new_filename: Optional[str] = MISSING,
118-
new_expires: Optional[datetime.datetime] = MISSING,
119-
) -> None:
120-
await self.http._edit_paste(paste_id)
132+
Fetch a paste.
133+
134+
Parameters
135+
-----------
136+
paste_id: :class:`str`
137+
The paste id to fetch.
138+
password: Optional[:class:`str`]
139+
The password of the paste, if any.
140+
"""
141+
data = await self.http._get_paste(paste_id=paste_id, password=password)
142+
return Paste._from_data(data)
143+
144+
# @overload
145+
# async def edit_paste(self, paste_id: str, *, new_content: str, new_filename: ..., new_expires: ...) -> None:
146+
# ...
147+
148+
# @overload
149+
# async def edit_paste(self, paste_id: str, *, new_content: ..., new_filename: str, new_expires: ...) -> None:
150+
# ...
151+
152+
# @overload
153+
# async def edit_paste(
154+
# self, paste_id: str, *, new_content: ..., new_filename: ..., new_expires: datetime.datetime
155+
# ) -> None:
156+
# ...
157+
158+
# @overload
159+
# async def edit_paste(self, paste_id: str, *, new_content: str, new_filename: str, new_expires: ...) -> None:
160+
# ...
161+
162+
# @overload
163+
# async def edit_paste(
164+
# self, paste_id: str, *, new_content: str, new_filename: ..., new_expires: datetime.datetime
165+
# ) -> None:
166+
# ...
167+
168+
# @overload
169+
# async def edit_paste(
170+
# self, paste_id: str, *, new_content: ..., new_filename: str, new_expires: datetime.datetime
171+
# ) -> None:
172+
# ...
173+
174+
# @overload
175+
# async def edit_paste(
176+
# self, paste_id: str, *, new_content: str, new_filename: str, new_expires: datetime.datetime
177+
# ) -> None:
178+
# ...
179+
180+
# @require_authentication
181+
# async def edit_paste(
182+
# self,
183+
# paste_id: str,
184+
# *,
185+
# new_content: Optional[str] = MISSING,
186+
# new_filename: Optional[str] = MISSING,
187+
# new_expires: Optional[datetime.datetime] = MISSING,
188+
# ) -> None:
189+
# await self.http._edit_paste(paste_id, new_content=new_content, new_filename=new_filename, new_expires=new_expires)
121190

122191
@require_authentication
123192
async def get_user_pastes(self, *, limit: int = 100) -> list[Paste]:
193+
"""|coro|
194+
195+
Get all pastes belonging to the current authenticated user.
196+
197+
Parameters
198+
-----------
199+
limit: :class:`int`
200+
The amount of pastes to fetch. Defaults to ``100``.
201+
202+
Returns
203+
--------
204+
list[:class:`Paste`]
205+
The pastes that were fetched.
206+
"""
124207
data = await self.http._get_my_pastes(limit=limit)
125208

126-
return [Paste.from_data(x) for x in data]
209+
return [Paste._from_data(x) for x in data]

‎mystbin/http.py

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -249,9 +249,9 @@ def _create_paste(
249249

250250
json_: dict[str, Any] = {}
251251
if file:
252-
json_["files"] = [file.to_dict()]
252+
json_["files"] = [file._to_dict()]
253253
elif files:
254-
json_["files"] = [f.to_dict() for f in files]
254+
json_["files"] = [f._to_dict() for f in files]
255255

256256
if password:
257257
json_["password"] = password

0 commit comments

Comments
 (0)