Skip to content

Commit ecc9228

Browse files
habara-khabara-k
committed
Add in-code docs
1 parent dffe681 commit ecc9228

File tree

3 files changed

+128
-2
lines changed

3 files changed

+128
-2
lines changed

‎generate-code.py‎

Lines changed: 52 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,53 @@ def run_command(command):
2121

2222
def add_stateless_channel_token_wrappers():
2323
for fname in ['channel_access_token.py', 'async_channel_access_token.py']:
24-
with open(f'linebot/v3/oauth/api/{fname}', 'a') as fp:
25-
for base_method in ['issue_stateless_channel_token', 'issue_stateless_channel_token_with_http_info']:
24+
filepath = f'linebot/v3/oauth/api/{fname}'
25+
26+
# Inject deprecation notes into original methods' docstrings
27+
with open(filepath, 'r') as fp:
28+
lines = fp.readlines()
29+
30+
new_lines = []
31+
i = 0
32+
while i < len(lines):
33+
new_lines.append(lines[i])
34+
for base_method in ['issue_stateless_channel_token_with_http_info',
35+
'issue_stateless_channel_token']:
36+
if f'def {base_method}(self' in lines[i]:
37+
# Next line: docstring title
38+
i += 1
39+
new_lines.append(lines[i])
40+
# Next line: blank line
41+
i += 1
42+
new_lines.append(lines[i])
43+
# Insert deprecation note
44+
new_lines.append(f' .. deprecated::\n')
45+
new_lines.append(f' Use :func:`{base_method}_by_jwt_assertion` or\n')
46+
new_lines.append(f' :func:`{base_method}_by_client_secret` instead.\n')
47+
new_lines.append('\n')
48+
break
49+
i += 1
50+
51+
with open(filepath, 'w') as fp:
52+
fp.writelines(new_lines)
53+
54+
# Append wrapper methods with docstrings
55+
with open(filepath, 'a') as fp:
56+
for base_method in ['issue_stateless_channel_token',
57+
'issue_stateless_channel_token_with_http_info']:
58+
if base_method == 'issue_stateless_channel_token':
59+
rtype = 'IssueStatelessChannelAccessTokenResponse'
60+
else:
61+
rtype = 'ApiResponse'
62+
2663
fp.write("\n")
2764
fp.write(f" def {base_method}_by_jwt_assertion(self, client_assertion, **kwargs):\n")
65+
fp.write(f' """Issue a stateless channel access token using a JSON Web Token (JWT).\n')
66+
fp.write(f'\n')
67+
fp.write(f' :param str client_assertion: A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.\n')
68+
fp.write(f' :return: Returns the result object.\n')
69+
fp.write(f' :rtype: {rtype}\n')
70+
fp.write(f' """\n')
2871
fp.write(f" return self.{base_method}(\n")
2972
fp.write(" grant_type='client_credentials',\n")
3073
fp.write(" client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer',\n")
@@ -35,6 +78,13 @@ def add_stateless_channel_token_wrappers():
3578
fp.write(" )\n")
3679
fp.write("\n")
3780
fp.write(f" def {base_method}_by_client_secret(self, client_id, client_secret, **kwargs):\n")
81+
fp.write(f' """Issue a stateless channel access token using client ID and client secret.\n')
82+
fp.write(f'\n')
83+
fp.write(f' :param str client_id: Channel ID.\n')
84+
fp.write(f' :param str client_secret: Channel secret.\n')
85+
fp.write(f' :return: Returns the result object.\n')
86+
fp.write(f' :rtype: {rtype}\n')
87+
fp.write(f' """\n')
3888
fp.write(f" return self.{base_method}(\n")
3989
fp.write(" grant_type='client_credentials',\n")
4090
fp.write(" client_assertion_type='',\n")

‎linebot/v3/oauth/api/async_channel_access_token.py‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -562,14 +562,26 @@ def issue_channel_token_by_jwt_with_http_info(self, grant_type : Annotated[Stric
562562
async def issue_stateless_channel_token(self, grant_type : Annotated[StrictStr, Field(..., description="`client_credentials`")], client_assertion_type : Annotated[StrictStr, Field(..., description="URL-encoded value of `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`")], client_assertion : Annotated[StrictStr, Field(..., description="A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.")], client_id : Annotated[StrictStr, Field(..., description="Channel ID.")], client_secret : Annotated[StrictStr, Field(..., description="Channel secret.")], **kwargs) -> IssueStatelessChannelAccessTokenResponse: # noqa: E501
563563
...
564564

565+
.. deprecated::
566+
Use :func:`issue_stateless_channel_token_by_jwt_assertion` or
567+
:func:`issue_stateless_channel_token_by_client_secret` instead.
568+
565569
@overload
566570
def issue_stateless_channel_token(self, grant_type : Annotated[StrictStr, Field(..., description="`client_credentials`")], client_assertion_type : Annotated[StrictStr, Field(..., description="URL-encoded value of `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`")], client_assertion : Annotated[StrictStr, Field(..., description="A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.")], client_id : Annotated[StrictStr, Field(..., description="Channel ID.")], client_secret : Annotated[StrictStr, Field(..., description="Channel secret.")], async_req: Optional[bool]=True, **kwargs) -> IssueStatelessChannelAccessTokenResponse: # noqa: E501
567571
...
568572

573+
.. deprecated::
574+
Use :func:`issue_stateless_channel_token_by_jwt_assertion` or
575+
:func:`issue_stateless_channel_token_by_client_secret` instead.
576+
569577
@validate_arguments
570578
def issue_stateless_channel_token(self, grant_type : Annotated[StrictStr, Field(..., description="`client_credentials`")], client_assertion_type : Annotated[StrictStr, Field(..., description="URL-encoded value of `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`")], client_assertion : Annotated[StrictStr, Field(..., description="A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.")], client_id : Annotated[StrictStr, Field(..., description="Channel ID.")], client_secret : Annotated[StrictStr, Field(..., description="Channel secret.")], async_req: Optional[bool]=None, **kwargs) -> Union[IssueStatelessChannelAccessTokenResponse, Awaitable[IssueStatelessChannelAccessTokenResponse]]: # noqa: E501
571579
"""issue_stateless_channel_token # noqa: E501
572580
581+
.. deprecated::
582+
Use :func:`issue_stateless_channel_token_by_jwt_assertion` or
583+
:func:`issue_stateless_channel_token_by_client_secret` instead.
584+
573585
Issues a new stateless channel access token, which doesn't have max active token limit unlike the other token types. The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires. # noqa: E501
574586
This method makes a synchronous HTTP request by default. To make an
575587
asynchronous HTTP request, please pass async_req=True
@@ -609,6 +621,10 @@ def issue_stateless_channel_token(self, grant_type : Annotated[StrictStr, Field(
609621
def issue_stateless_channel_token_with_http_info(self, grant_type : Annotated[StrictStr, Field(..., description="`client_credentials`")], client_assertion_type : Annotated[StrictStr, Field(..., description="URL-encoded value of `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`")], client_assertion : Annotated[StrictStr, Field(..., description="A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.")], client_id : Annotated[StrictStr, Field(..., description="Channel ID.")], client_secret : Annotated[StrictStr, Field(..., description="Channel secret.")], **kwargs) -> ApiResponse: # noqa: E501
610622
"""issue_stateless_channel_token # noqa: E501
611623
624+
.. deprecated::
625+
Use :func:`issue_stateless_channel_token_with_http_info_by_jwt_assertion` or
626+
:func:`issue_stateless_channel_token_with_http_info_by_client_secret` instead.
627+
612628
Issues a new stateless channel access token, which doesn't have max active token limit unlike the other token types. The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires. # noqa: E501
613629
This method makes a synchronous HTTP request by default. To make an
614630
asynchronous HTTP request, please pass async_req=True
@@ -1378,6 +1394,12 @@ def verify_channel_token_by_jwt_with_http_info(self, access_token : Annotated[St
13781394
_request_auth=_params.get('_request_auth'))
13791395

13801396
def issue_stateless_channel_token_by_jwt_assertion(self, client_assertion, **kwargs):
1397+
"""Issue a stateless channel access token using a JSON Web Token (JWT).
1398+
1399+
:param str client_assertion: A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.
1400+
:return: Returns the result object.
1401+
:rtype: IssueStatelessChannelAccessTokenResponse
1402+
"""
13811403
return self.issue_stateless_channel_token(
13821404
grant_type='client_credentials',
13831405
client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
@@ -1388,6 +1410,13 @@ def issue_stateless_channel_token_by_jwt_assertion(self, client_assertion, **kwa
13881410
)
13891411

13901412
def issue_stateless_channel_token_by_client_secret(self, client_id, client_secret, **kwargs):
1413+
"""Issue a stateless channel access token using client ID and client secret.
1414+
1415+
:param str client_id: Channel ID.
1416+
:param str client_secret: Channel secret.
1417+
:return: Returns the result object.
1418+
:rtype: IssueStatelessChannelAccessTokenResponse
1419+
"""
13911420
return self.issue_stateless_channel_token(
13921421
grant_type='client_credentials',
13931422
client_assertion_type='',
@@ -1398,6 +1427,12 @@ def issue_stateless_channel_token_by_client_secret(self, client_id, client_secre
13981427
)
13991428

14001429
def issue_stateless_channel_token_with_http_info_by_jwt_assertion(self, client_assertion, **kwargs):
1430+
"""Issue a stateless channel access token using a JSON Web Token (JWT).
1431+
1432+
:param str client_assertion: A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.
1433+
:return: Returns the result object.
1434+
:rtype: ApiResponse
1435+
"""
14011436
return self.issue_stateless_channel_token_with_http_info(
14021437
grant_type='client_credentials',
14031438
client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
@@ -1408,6 +1443,13 @@ def issue_stateless_channel_token_with_http_info_by_jwt_assertion(self, client_a
14081443
)
14091444

14101445
def issue_stateless_channel_token_with_http_info_by_client_secret(self, client_id, client_secret, **kwargs):
1446+
"""Issue a stateless channel access token using client ID and client secret.
1447+
1448+
:param str client_id: Channel ID.
1449+
:param str client_secret: Channel secret.
1450+
:return: Returns the result object.
1451+
:rtype: ApiResponse
1452+
"""
14111453
return self.issue_stateless_channel_token_with_http_info(
14121454
grant_type='client_credentials',
14131455
client_assertion_type='',

‎linebot/v3/oauth/api/channel_access_token.py‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -530,6 +530,10 @@ def issue_channel_token_by_jwt_with_http_info(self, grant_type : Annotated[Stric
530530
def issue_stateless_channel_token(self, grant_type : Annotated[StrictStr, Field(..., description="`client_credentials`")], client_assertion_type : Annotated[StrictStr, Field(..., description="URL-encoded value of `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`")], client_assertion : Annotated[StrictStr, Field(..., description="A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.")], client_id : Annotated[StrictStr, Field(..., description="Channel ID.")], client_secret : Annotated[StrictStr, Field(..., description="Channel secret.")], **kwargs) -> IssueStatelessChannelAccessTokenResponse: # noqa: E501
531531
"""issue_stateless_channel_token # noqa: E501
532532
533+
.. deprecated::
534+
Use :func:`issue_stateless_channel_token_by_jwt_assertion` or
535+
:func:`issue_stateless_channel_token_by_client_secret` instead.
536+
533537
Issues a new stateless channel access token, which doesn't have max active token limit unlike the other token types. The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires. # noqa: E501
534538
This method makes a synchronous HTTP request by default. To make an
535539
asynchronous HTTP request, please pass async_req=True
@@ -567,6 +571,10 @@ def issue_stateless_channel_token(self, grant_type : Annotated[StrictStr, Field(
567571
def issue_stateless_channel_token_with_http_info(self, grant_type : Annotated[StrictStr, Field(..., description="`client_credentials`")], client_assertion_type : Annotated[StrictStr, Field(..., description="URL-encoded value of `urn:ietf:params:oauth:client-assertion-type:jwt-bearer`")], client_assertion : Annotated[StrictStr, Field(..., description="A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.")], client_id : Annotated[StrictStr, Field(..., description="Channel ID.")], client_secret : Annotated[StrictStr, Field(..., description="Channel secret.")], **kwargs) -> ApiResponse: # noqa: E501
568572
"""issue_stateless_channel_token # noqa: E501
569573
574+
.. deprecated::
575+
Use :func:`issue_stateless_channel_token_with_http_info_by_jwt_assertion` or
576+
:func:`issue_stateless_channel_token_with_http_info_by_client_secret` instead.
577+
570578
Issues a new stateless channel access token, which doesn't have max active token limit unlike the other token types. The newly issued token is only valid for 15 minutes but can not be revoked until it naturally expires. # noqa: E501
571579
This method makes a synchronous HTTP request by default. To make an
572580
asynchronous HTTP request, please pass async_req=True
@@ -1296,6 +1304,12 @@ def verify_channel_token_by_jwt_with_http_info(self, access_token : Annotated[St
12961304
_request_auth=_params.get('_request_auth'))
12971305

12981306
def issue_stateless_channel_token_by_jwt_assertion(self, client_assertion, **kwargs):
1307+
"""Issue a stateless channel access token using a JSON Web Token (JWT).
1308+
1309+
:param str client_assertion: A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.
1310+
:return: Returns the result object.
1311+
:rtype: IssueStatelessChannelAccessTokenResponse
1312+
"""
12991313
return self.issue_stateless_channel_token(
13001314
grant_type='client_credentials',
13011315
client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
@@ -1306,6 +1320,13 @@ def issue_stateless_channel_token_by_jwt_assertion(self, client_assertion, **kwa
13061320
)
13071321

13081322
def issue_stateless_channel_token_by_client_secret(self, client_id, client_secret, **kwargs):
1323+
"""Issue a stateless channel access token using client ID and client secret.
1324+
1325+
:param str client_id: Channel ID.
1326+
:param str client_secret: Channel secret.
1327+
:return: Returns the result object.
1328+
:rtype: IssueStatelessChannelAccessTokenResponse
1329+
"""
13091330
return self.issue_stateless_channel_token(
13101331
grant_type='client_credentials',
13111332
client_assertion_type='',
@@ -1316,6 +1337,12 @@ def issue_stateless_channel_token_by_client_secret(self, client_id, client_secre
13161337
)
13171338

13181339
def issue_stateless_channel_token_with_http_info_by_jwt_assertion(self, client_assertion, **kwargs):
1340+
"""Issue a stateless channel access token using a JSON Web Token (JWT).
1341+
1342+
:param str client_assertion: A JSON Web Token the client needs to create and sign with the private key of the Assertion Signing Key.
1343+
:return: Returns the result object.
1344+
:rtype: ApiResponse
1345+
"""
13191346
return self.issue_stateless_channel_token_with_http_info(
13201347
grant_type='client_credentials',
13211348
client_assertion_type='urn:ietf:params:oauth:client-assertion-type:jwt-bearer',
@@ -1326,6 +1353,13 @@ def issue_stateless_channel_token_with_http_info_by_jwt_assertion(self, client_a
13261353
)
13271354

13281355
def issue_stateless_channel_token_with_http_info_by_client_secret(self, client_id, client_secret, **kwargs):
1356+
"""Issue a stateless channel access token using client ID and client secret.
1357+
1358+
:param str client_id: Channel ID.
1359+
:param str client_secret: Channel secret.
1360+
:return: Returns the result object.
1361+
:rtype: ApiResponse
1362+
"""
13291363
return self.issue_stateless_channel_token_with_http_info(
13301364
grant_type='client_credentials',
13311365
client_assertion_type='',

0 commit comments

Comments
 (0)