Skip to content

Commit 78f08c4

Browse files
jsmnbomjsmnbom
committed
Make passport docstrings better
1 parent 72d2fd5 commit 78f08c4

File tree

7 files changed

+110
-77
lines changed

7 files changed

+110
-77
lines changed

‎telegram/files/file.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,10 @@ class File(TelegramObject):
4646
bot (:obj:`telegram.Bot`, optional): Bot to use with shortcut method.
4747
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
4848
49+
Note:
50+
If you obtain an instance of this class from :attr:`telegram.PassportFile.get_file`,
51+
then it will automatically be decrypted as it downloads when you call :attr:`download()`.
52+
4953
"""
5054

5155
def __init__(self, file_id, bot=None, file_size=None, file_path=None, **kwargs):

‎telegram/passport/credentials.py‎

Lines changed: 22 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -99,22 +99,27 @@ class EncryptedCredentials(TelegramObject):
9999
authentication processes.
100100
101101
Attributes:
102-
data (:obj:`str`): Base64-encoded encrypted JSON-serialized data with unique user's
103-
payload, data hashes and secrets required for EncryptedPassportElement decryption and
104-
authentication
105-
hash (:obj:`str`): Base64-encoded data hash for data authentication
106-
secret (:obj:`str`): Base64-encoded secret, encrypted with the bot's public RSA key,
107-
required for data decryption
102+
data (:class:`telegram.Credentials`): Decrypted data with unique user's payload,
103+
data hashes and secrets used for EncryptedPassportElement decryption and
104+
authentication.
105+
hash (:obj:`str`): Base64-encoded data hash for data authentication.
106+
secret (:obj:`str`): Decrypted secret used for decryption.
108107
109108
Args:
110109
data (:obj:`str`): Base64-encoded encrypted JSON-serialized data with unique user's
111110
payload, data hashes and secrets required for EncryptedPassportElement decryption and
112-
authentication
113-
hash (:obj:`str`): Base64-encoded data hash for data authentication
111+
authentication.
112+
hash (:obj:`str`): Base64-encoded data hash for data authentication.
114113
secret (:obj:`str`): Base64-encoded secret, encrypted with the bot's public RSA key,
115-
required for data decryption
114+
required for data decryption.
116115
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
117116
117+
Note:
118+
Python-telegram-bot automatically decrypts your :class:`telegram.PassportData` objects for
119+
you if you set a private key when initializing :class:`telegram.Bot` or
120+
:class:`telegram.Updater`, this means that you should only need
121+
this class for the :attr:`telegram.Credentials.payload` attribute on the object in the
122+
:attr:`data` attribute.
118123
"""
119124

120125
def __init__(self, data, hash, secret, bot=None, **kwargs):
@@ -161,6 +166,12 @@ class Credentials(TelegramObject):
161166
Attributes:
162167
secure_data (:class:`telegram.SecureData`): Credentials for encrypted data
163168
payload (:obj:`str`): Bot-specified payload
169+
170+
Note:
171+
Python-telegram-bot automatically decrypts your :class:`telegram.PassportData` objects for
172+
you if you set a private key when initializing :class:`telegram.Bot` or
173+
:class:`telegram.Updater`, this means that you should only need
174+
this class for its :attr:`payload` attribute.
164175
"""
165176

166177
def __init__(self, secure_data, payload, bot=None, **kwargs):
@@ -182,7 +193,7 @@ def de_json(cls, data, bot):
182193

183194
class SecureData(TelegramObject):
184195
"""
185-
This object represents the credentials required to decrypt encrypted data.
196+
This object represents the credentials that were used to decrypt the encrypted data.
186197
All fields are optional and depend on fields that were requested.
187198
188199
Attributes:
@@ -261,7 +272,7 @@ def de_json(cls, data, bot):
261272

262273
class SecureValue(TelegramObject):
263274
"""
264-
This object represents the credentials required to decrypt encrypted value.
275+
This object represents the credentials that were used to decrypt the encrypted value.
265276
All fields are optional and depend on the type of field.
266277
267278
Attributes:

‎telegram/passport/data.py‎

Lines changed: 15 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -24,12 +24,13 @@ class PersonalDetails(TelegramObject):
2424
This object represents personal details.
2525
2626
Attributes:
27-
first_name (:obj:`str`): First Name
28-
last_name (:obj:`str`): Last Name
29-
birth_date (:obj:`str`): Date of birth in DD.MM.YYYY format
30-
gender (:obj:`str`): Gender, male or female
31-
country_code (:obj:`str`): Citizenship (ISO 3166-1 alpha-2 country code)
32-
residence_country_code (:obj:`str`): Country of residence (ISO 3166-1 alpha-2 country code)
27+
first_name (:obj:`str`): First Name.
28+
last_name (:obj:`str`): Last Name.
29+
birth_date (:obj:`str`): Date of birth in DD.MM.YYYY format.
30+
gender (:obj:`str`): Gender, male or female.
31+
country_code (:obj:`str`): Citizenship (ISO 3166-1 alpha-2 country code).
32+
residence_country_code (:obj:`str`): Country of residence (ISO 3166-1 alpha-2 country
33+
code).
3334
"""
3435

3536
def __init__(self, first_name, last_name, birth_date, gender, country_code,
@@ -57,12 +58,12 @@ class ResidentialAddress(TelegramObject):
5758
This object represents a residential address.
5859
5960
Attributes:
60-
street_line1 (:obj:`str`): First line for the address
61-
street_line2 (:obj:`str`): Optional. Second line for the address
62-
city (:obj:`str`): City
63-
state (:obj:`str`): Optional. State
64-
country_code (:obj:`str`): ISO 3166-1 alpha-2 country code
65-
post_code (:obj:`str`): Address post code
61+
street_line1 (:obj:`str`): First line for the address.
62+
street_line2 (:obj:`str`): Optional. Second line for the address.
63+
city (:obj:`str`): City.
64+
state (:obj:`str`): Optional. State.
65+
country_code (:obj:`str`): ISO 3166-1 alpha-2 country code.
66+
post_code (:obj:`str`): Address post code.
6667
"""
6768

6869
def __init__(self, street_line1, street_line2, city, state, country_code,
@@ -90,8 +91,8 @@ class IdDocumentData(TelegramObject):
9091
This object represents the data of an identity document.
9192
9293
Attributes:
93-
document_no (:obj:`str`): Document number
94-
expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format
94+
document_no (:obj:`str`): Document number.
95+
expiry_date (:obj:`str`): Optional. Date of expiry, in DD.MM.YYYY format.
9596
"""
9697

9798
def __init__(self, document_no, expiry_date, bot=None, **kwargs):

‎telegram/passport/encryptedpassportelement.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@
2525

2626
class EncryptedPassportElement(TelegramObject):
2727
"""Contains information about documents or other Telegram Passport elements shared with the bot
28-
by the user.
28+
by the user. The data has been automatically decrypted by python-telegram-bot.
2929
3030
Attributes:
3131
type (:obj:`str`): Element type. One of "personal_details", "passport", "driver_license",

‎telegram/passport/passportdata.py‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -28,20 +28,27 @@ class PassportData(TelegramObject):
2828
2929
Attributes:
3030
data (List[:class:`telegram.EncryptedPassportElement`]): Array with information about
31-
documents and other Telegram Passport elements that was shared with the bot
32-
credentials (:class:`telegram.EncryptedCredentials`): Encrypted credentials required to
33-
decrypt the data
31+
documents and other Telegram Passport elements that was shared with the bot.
32+
credentials (:class:`telegram.EncryptedCredentials`): Encrypted credentials that were
33+
used to decrypt the data. This object also contains the user specified payload as
34+
`data.payload`.
3435
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
3536
36-
3737
Args:
3838
data (List[:class:`telegram.EncryptedPassportElement`]): Array with information about
39-
documents and other Telegram Passport elements that was shared with the bot
40-
credentials (:class:`telegram.EncryptedCredentials`): Encrypted credentials required to
41-
decrypt the data
39+
documents and other Telegram Passport elements that was shared with the bot.
40+
credentials (:class:`telegram.EncryptedCredentials`): Encrypted credentials that will be
41+
used to decrypt the data
4242
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
4343
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
4444
45+
Note:
46+
Python-telegram-bot automatically decrypts your :class:`telegram.PassportData` objects for
47+
you if you set a private key when initializing :class:`telegram.Bot` or
48+
:class:`telegram.Updater`, This means that the data in the :attr:`data`
49+
attribute despite its name, :class:`telegram.EncryptedPassportElement`, is in fact
50+
decrypted.
51+
4552
"""
4653

4754
def __init__(self, data, credentials, bot=None, **kwargs):

‎telegram/passport/passportelementerrors.py‎

Lines changed: 40 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -53,18 +53,18 @@ class PassportElementErrorDataField(PassportElementError):
5353
Attributes:
5454
type (:obj:`str`): The section of the user's Telegram Passport which has the error, one of
5555
"personal_details", "passport", "driver_license", "identity_card", "internal_passport",
56-
"address"
57-
field_name (:obj:`str`): Name of the data field which has the error
58-
data_hash (:obj:`str`): Base64-encoded data hash
59-
message (:obj:`str`): Error message
56+
"address".
57+
field_name (:obj:`str`): Name of the data field which has the error.
58+
data_hash (:obj:`str`): Base64-encoded data hash.
59+
message (:obj:`str`): Error message.
6060
6161
Args:
6262
type (:obj:`str`): The section of the user's Telegram Passport which has the error, one of
6363
"personal_details", "passport", "driver_license", "identity_card", "internal_passport",
64-
"address"
65-
field_name (:obj:`str`): Name of the data field which has the error
66-
data_hash (:obj:`str`): Base64-encoded data hash
67-
message (:obj:`str`): Error message
64+
"address".
65+
field_name (:obj:`str`): Name of the data field which has the error.
66+
data_hash (:obj:`str`): Base64-encoded data hash.
67+
message (:obj:`str`): Error message.
6868
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
6969
7070
"""
@@ -91,16 +91,16 @@ class PassportElementErrorFile(PassportElementError):
9191
Attributes:
9292
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
9393
"utility_bill", "bank_statement", "rental_agreement", "passport_registration",
94-
"temporary_registration"
95-
file_hash (:obj:`str`): Base64-encoded file hash
96-
message (:obj:`str`): Error message
94+
"temporary_registration".
95+
file_hash (:obj:`str`): Base64-encoded file hash.
96+
message (:obj:`str`): Error message.
9797
9898
Args:
9999
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
100100
"utility_bill", "bank_statement", "rental_agreement", "passport_registration",
101-
"temporary_registration"
102-
file_hash (:obj:`str`): Base64-encoded file hash
103-
message (:obj:`str`): Error message
101+
"temporary_registration".
102+
file_hash (:obj:`str`): Base64-encoded file hash.
103+
message (:obj:`str`): Error message.
104104
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
105105
106106
"""
@@ -125,16 +125,16 @@ class PassportElementErrorFiles(PassportElementError):
125125
Attributes:
126126
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
127127
"utility_bill", "bank_statement", "rental_agreement", "passport_registration",
128-
"temporary_registration"
129-
file_hash (:obj:`str`): Base64-encoded data hash
130-
message (:obj:`str`): Error message
128+
"temporary_registration".
129+
file_hash (:obj:`str`): Base64-encoded file hash.
130+
message (:obj:`str`): Error message.
131131
132132
Args:
133133
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
134134
"utility_bill", "bank_statement", "rental_agreement", "passport_registration",
135-
"temporary_registration"
136-
file_hashes (List[:obj:`str`]): List of base64-encoded file hashes
137-
message (:obj:`str`): Error message
135+
"temporary_registration".
136+
file_hashes (List[:obj:`str`]): List of base64-encoded file hashes.
137+
message (:obj:`str`): Error message.
138138
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
139139
140140
"""
@@ -159,15 +159,17 @@ class PassportElementErrorFrontSide(PassportElementError):
159159
160160
Attributes:
161161
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
162-
"passport", "driver_license", "identity_card", "internal_passport"
163-
file_hash (:obj:`str`): Base64-encoded hash of the file with the front side of the document
164-
message (:obj:`str`): Error message
162+
"passport", "driver_license", "identity_card", "internal_passport".
163+
file_hash (:obj:`str`): Base64-encoded hash of the file with the front side of the
164+
document.
165+
message (:obj:`str`): Error message.
165166
166167
Args:
167168
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
168-
"passport", "driver_license", "identity_card", "internal_passport"
169-
file_hash (:obj:`str`): Base64-encoded hash of the file with the front side of the document
170-
message (:obj:`str`): Error message
169+
"passport", "driver_license", "identity_card", "internal_passport".
170+
file_hash (:obj:`str`): Base64-encoded hash of the file with the front side of the
171+
document.
172+
message (:obj:`str`): Error message.
171173
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
172174
173175
"""
@@ -191,17 +193,17 @@ class PassportElementErrorReverseSide(PassportElementError):
191193
192194
Attributes:
193195
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
194-
"passport", "driver_license", "identity_card", "internal_passport"
196+
"passport", "driver_license", "identity_card", "internal_passport".
195197
file_hash (:obj:`str`): Base64-encoded hash of the file with the reverse side of the
196-
document
197-
message (:obj:`str`): Error message
198+
document.
199+
message (:obj:`str`): Error message.
198200
199201
Args:
200202
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
201-
"driver_license", "identity_card"
203+
"driver_license", "identity_card".
202204
file_hash (:obj:`str`): Base64-encoded hash of the file with the reverse side of the
203-
document
204-
message (:obj:`str`): Error message
205+
document.
206+
message (:obj:`str`): Error message.
205207
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
206208
207209
"""
@@ -225,15 +227,15 @@ class PassportElementErrorSelfie(PassportElementError):
225227
226228
Attributes:
227229
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
228-
"passport", "driver_license", "identity_card", "internal_passport"
229-
file_hash (:obj:`str`): Base64-encoded hash of the file with the selfie
230-
message (:obj:`str`): Error message
230+
"passport", "driver_license", "identity_card", "internal_passport".
231+
file_hash (:obj:`str`): Base64-encoded hash of the file with the selfie.
232+
message (:obj:`str`): Error message.
231233
232234
Args:
233235
type (:obj:`str`): The section of the user's Telegram Passport which has the issue, one of
234-
"passport", "driver_license", "identity_card", "internal_passport"
235-
file_hash (:obj:`str`): Base64-encoded hash of the file with the selfie
236-
message (:obj:`str`): Error message
236+
"passport", "driver_license", "identity_card", "internal_passport".
237+
file_hash (:obj:`str`): Base64-encoded hash of the file with the selfie.
238+
message (:obj:`str`): Error message.
237239
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
238240
239241
"""

‎telegram/passport/passportfile.py‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,18 +27,26 @@ class PassportFile(TelegramObject):
2727
authentication processes.
2828
2929
Attributes:
30-
file_id (:obj:`str`): Unique identifier for this file
31-
file_size (:obj:`int`): File size
32-
file_date (:obj:`int`): Unix time when the file was uploaded
30+
file_id (:obj:`str`): Unique identifier for this file.
31+
file_size (:obj:`int`): File size.
32+
file_date (:obj:`int`): Unix time when the file was uploaded.
3333
bot (:class:`telegram.Bot`): Optional. The Bot to use for instance methods.
3434
3535
Args:
36-
file_id (:obj:`str`): Unique identifier for this file
37-
file_size (:obj:`int`): File size
38-
file_date (:obj:`int`): Unix time when the file was uploaded
36+
file_id (:obj:`str`): Unique identifier for this file.
37+
file_size (:obj:`int`): File size.
38+
file_date (:obj:`int`): Unix time when the file was uploaded.
3939
bot (:class:`telegram.Bot`, optional): The Bot to use for instance methods.
4040
**kwargs (:obj:`dict`): Arbitrary keyword arguments.
4141
42+
Note:
43+
Python-telegram-bot automatically decrypts your :class:`telegram.PassportData` objects for
44+
you if you set a private key when initializing :class:`telegram.Bot` or
45+
:class:`telegram.Updater`, this also applies to files,
46+
but only when you use :attr:`telegram.PassportFile.get_file` to get your
47+
:class:`telegram.File` object (that you can then :attr:`telegram.File.download()` to
48+
download the decrypted version of).
49+
4250
"""
4351

4452
def __init__(self, file_id, file_date, file_size=None, bot=None, credentials=None, **kwargs):

0 commit comments

Comments
 (0)