9067377560

Committed 13 May 2024 05:40PM UTC coverage: 96.426% (+0.008%) from 96.418%

Build # 9067377560

Build Type

push

github

Committed by

web-flow

Commit Message

(beta) swap from `black` to `ruff` for formatting (#1330)

* (beta) swap from black to ruff

* (beta) mass-format with ruff

* (beta) add git-blame-ignore-revs

Run Details

1338 of 2019 branches covered (66.27%)

Branch coverage included in aggregate %.

100 of 100 new or added lines in 79 files covered. (100.0%)

189 existing lines in 95 files now uncovered.

82348 of 84769 relevant lines covered (97.14%)

0.97 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

94.64

/stripe/_file.py

# -*- coding: utf-8 -*-
# File generated from our OpenAPI spec
from stripe._createable_api_resource import CreateableAPIResource
from stripe._list_object import ListObject
from stripe._listable_api_resource import ListableAPIResource
from stripe._request_options import RequestOptions
from typing import Any, ClassVar, Dict, List, Optional, cast
from typing_extensions import (
    Literal,
    NotRequired,
    TypedDict,
    Unpack,
    TYPE_CHECKING,
)

if TYPE_CHECKING:
    from stripe._file_link import FileLink


class File(CreateableAPIResource["File"], ListableAPIResource["File"]):
    """
    This object represents files hosted on Stripe's servers. You can upload
    files with the [create file](https://stripe.com/docs/api#create_file) request
    (for example, when uploading dispute evidence). Stripe also
    creates files independently (for example, the results of a [Sigma scheduled
    query](https://stripe.com/docs/api#scheduled_queries)).

    Related guide: [File upload guide](https://stripe.com/docs/file-upload)
    """

    OBJECT_NAME: ClassVar[Literal["file"]] = "file"

    class CreateParams(RequestOptions):
        expand: NotRequired[List[str]]
        """
        Specifies which fields in the response should be expanded.
        """
        file: Any
        """
        A file to upload. Make sure that the specifications follow RFC 2388, which defines file transfers for the `multipart/form-data` protocol.
        """
        file_link_data: NotRequired["File.CreateParamsFileLinkData"]
        """
        Optional parameters that automatically create a [file link](https://stripe.com/docs/api#file_links) for the newly created file.
        """
        purpose: Literal[
            "account_requirement",
            "additional_verification",
            "business_icon",
            "business_logo",
            "customer_signature",
            "dispute_evidence",
            "identity_document",
            "pci_document",
            "tax_document_user_upload",
            "terminal_reader_splashscreen",
        ]
        """
        The [purpose](https://stripe.com/docs/file-upload#uploading-a-file) of the uploaded file.
        """

    class CreateParamsFileLinkData(TypedDict):
        create: bool
        """
        Set this to `true` to create a file link for the newly created file. Creating a link is only possible when the file's `purpose` is one of the following: `business_icon`, `business_logo`, `customer_signature`, `dispute_evidence`, `pci_document`, `tax_document_user_upload`, or `terminal_reader_splashscreen`.
        """
        expires_at: NotRequired[int]
        """
        The link isn't available after this future timestamp.
        """
        metadata: NotRequired["Literal['']|Dict[str, str]"]
        """
        Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
        """

    class ListParams(RequestOptions):
        created: NotRequired["File.ListParamsCreated|int"]
        """
        Only return files that were created during the given date interval.
        """
        ending_before: NotRequired[str]
        """
        A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
        """
        expand: NotRequired[List[str]]
        """
        Specifies which fields in the response should be expanded.
        """
        limit: NotRequired[int]
        """
        A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
        """
        purpose: NotRequired[
            Literal[
                "account_requirement",
                "additional_verification",
                "business_icon",
                "business_logo",
                "customer_signature",
                "dispute_evidence",
                "document_provider_identity_document",
                "finance_report_run",
                "identity_document",
                "identity_document_downloadable",
                "pci_document",
                "selfie",
                "sigma_scheduled_query",
                "tax_document_user_upload",
                "terminal_reader_splashscreen",
            ]
        ]
        """
        Filter queries by the file purpose. If you don't provide a purpose, the queries return unfiltered files.
        """
        starting_after: NotRequired[str]
        """
        A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
        """

    class ListParamsCreated(TypedDict):
        gt: NotRequired[int]
        """
        Minimum value to filter by (exclusive)
        """
        gte: NotRequired[int]
        """
        Minimum value to filter by (inclusive)
        """
        lt: NotRequired[int]
        """
        Maximum value to filter by (exclusive)
        """
        lte: NotRequired[int]
        """
        Maximum value to filter by (inclusive)
        """

    class RetrieveParams(RequestOptions):
        expand: NotRequired[List[str]]
        """
        Specifies which fields in the response should be expanded.
        """

    created: int
    """
    Time at which the object was created. Measured in seconds since the Unix epoch.
    """
    expires_at: Optional[int]
    """
    The file expires and isn't available at this time in epoch seconds.
    """
    filename: Optional[str]
    """
    The suitable name for saving the file to a filesystem.
    """
    id: str
    """
    Unique identifier for the object.
    """
    links: Optional[ListObject["FileLink"]]
    """
    A list of [file links](https://stripe.com/docs/api#file_links) that point at this file.
    """
    object: Literal["file"]
    """
    String representing the object's type. Objects of the same type share the same value.
    """
    purpose: Literal[
        "account_requirement",
        "additional_verification",
        "business_icon",
        "business_logo",
        "customer_signature",
        "dispute_evidence",
        "document_provider_identity_document",
        "finance_report_run",
        "identity_document",
        "identity_document_downloadable",
        "pci_document",
        "selfie",
        "sigma_scheduled_query",
        "tax_document_user_upload",
        "terminal_reader_splashscreen",
    ]
    """
    The [purpose](https://stripe.com/docs/file-upload#uploading-a-file) of the uploaded file.
    """
    size: int
    """
    The size of the file object in bytes.
    """
    title: Optional[str]
    """
    A suitable title for the document.
    """
    type: Optional[str]
    """
    The returned file type (for example, `csv`, `pdf`, `jpg`, or `png`).
    """
    url: Optional[str]
    """
    Use your live secret API key to download the file from this URL.
    """

    @classmethod
    def create(cls, **params: Unpack["File.CreateParams"]) -> "File":
        """
        To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.

        All of Stripe's officially supported Client libraries support sending multipart/form-data.
        """
        return cast(
            "File",
            cls._static_request(
                "post",
                cls.class_url(),
                params=params,
                base_address="files",
                api_mode="V1FILES",
            ),
        )

    @classmethod
    async def create_async(
        cls, **params: Unpack["File.CreateParams"]
    ) -> "File":
        """
        To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.

        All of Stripe's officially supported Client libraries support sending multipart/form-data.
        """
        return cast(
            "File",
            await cls._static_request_async(
                "post",
                cls.class_url(),
                params=params,
                base_address="files",
                api_mode="V1FILES",
            ),
        )

    @classmethod
    def list(cls, **params: Unpack["File.ListParams"]) -> ListObject["File"]:
        """
        Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.
        """
        result = cls._static_request(
            "get",
            cls.class_url(),
            params=params,
        )
        if not isinstance(result, ListObject):
            raise TypeError(
                "Expected list object from API, got %s"
                % (type(result).__name__)
            )

        return result

    @classmethod
    async def list_async(
        cls, **params: Unpack["File.ListParams"]
    ) -> ListObject["File"]:
        """
        Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.
        """
        result = await cls._static_request_async(
            "get",
            cls.class_url(),
            params=params,
        )
        if not isinstance(result, ListObject):
            raise TypeError(
                "Expected list object from API, got %s"
                % (type(result).__name__)
            )

        return result

    @classmethod
    def retrieve(
        cls, id: str, **params: Unpack["File.RetrieveParams"]
    ) -> "File":
        """
        Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to [access file contents](https://stripe.com/docs/file-upload#download-file-contents).
        """
        instance = cls(id, **params)
        instance.refresh()
        return instance

    @classmethod
    async def retrieve_async(
        cls, id: str, **params: Unpack["File.RetrieveParams"]
    ) -> "File":
        """
        Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to [access file contents](https://stripe.com/docs/file-upload#download-file-contents).
        """
        instance = cls(id, **params)
        await instance.refresh_async()
        return instance

    # This resource can have two different object names. In latter API
    # versions, only `file` is used, but since stripe-python may be used with
    # any API version, we need to support deserializing the older
    # `file_upload` object into the same class.
    OBJECT_NAME_ALT = "file_upload"

    @classmethod
    def class_url(cls):
        return "/v1/files"


# For backwards compatibility, the `File` class is aliased to `FileUpload`.
FileUpload = File

1	# -- coding: utf-8 --
2	# File generated from our OpenAPI spec
3	from stripe._createable_api_resource import CreateableAPIResource	1✔
4	from stripe._list_object import ListObject	1✔
5	from stripe._listable_api_resource import ListableAPIResource	1✔
6	from stripe._request_options import RequestOptions	1✔
7	from typing import Any, ClassVar, Dict, List, Optional, cast	1✔
8	from typing_extensions import (	1✔
9	Literal,
10	NotRequired,
11	TypedDict,
12	Unpack,
13	TYPE_CHECKING,
14	)
15
16	if TYPE_CHECKING:	1!
17	from stripe._file_link import FileLink	×
18
19
20	class File(CreateableAPIResource["File"], ListableAPIResource["File"]):	1✔
21	"""
22	This object represents files hosted on Stripe's servers. You can upload
23	files with the [create file](https://stripe.com/docs/api#create_file) request
24	(for example, when uploading dispute evidence). Stripe also
25	creates files independently (for example, the results of a [Sigma scheduled
26	query](https://stripe.com/docs/api#scheduled_queries)).
27
28	Related guide: [File upload guide](https://stripe.com/docs/file-upload)
29	"""
30
31	OBJECT_NAME: ClassVar[Literal["file"]] = "file"	1✔
32
33	class CreateParams(RequestOptions):	1✔
34	expand: NotRequired[List[str]]	1✔
35	"""	1✔
36	Specifies which fields in the response should be expanded.
37	"""
38	file: Any	1✔
39	"""	1✔
40	A file to upload. Make sure that the specifications follow RFC 2388, which defines file transfers for the `multipart/form-data` protocol.
41	"""
42	file_link_data: NotRequired["File.CreateParamsFileLinkData"]	1✔
43	"""	1✔
44	Optional parameters that automatically create a [file link](https://stripe.com/docs/api#file_links) for the newly created file.
45	"""
46	purpose: Literal[	1✔
47	"account_requirement",
48	"additional_verification",
49	"business_icon",
50	"business_logo",
51	"customer_signature",
52	"dispute_evidence",
53	"identity_document",
54	"pci_document",
55	"tax_document_user_upload",
56	"terminal_reader_splashscreen",
57	]
58	"""	1✔
59	The [purpose](https://stripe.com/docs/file-upload#uploading-a-file) of the uploaded file.
60	"""
61
62	class CreateParamsFileLinkData(TypedDict):	1✔
63	create: bool	1✔
64	"""	1✔
65	Set this to `true` to create a file link for the newly created file. Creating a link is only possible when the file's `purpose` is one of the following: `business_icon`, `business_logo`, `customer_signature`, `dispute_evidence`, `pci_document`, `tax_document_user_upload`, or `terminal_reader_splashscreen`.
66	"""
67	expires_at: NotRequired[int]	1✔
68	"""	1✔
69	The link isn't available after this future timestamp.
70	"""
71	metadata: NotRequired["Literal['']\|Dict[str, str]"]	1✔
72	"""	1✔
73	Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to `metadata`.
74	"""
75
76	class ListParams(RequestOptions):	1✔
77	created: NotRequired["File.ListParamsCreated\|int"]	1✔
78	"""	1✔
79	Only return files that were created during the given date interval.
80	"""
81	ending_before: NotRequired[str]	1✔
82	"""	1✔
83	A cursor for use in pagination. `ending_before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with `obj_bar`, your subsequent call can include `ending_before=obj_bar` in order to fetch the previous page of the list.
84	"""
85	expand: NotRequired[List[str]]	1✔
86	"""	1✔
87	Specifies which fields in the response should be expanded.
88	"""
89	limit: NotRequired[int]	1✔
90	"""	1✔
91	A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
92	"""
93	purpose: NotRequired[	1✔
94	Literal[
95	"account_requirement",
96	"additional_verification",
97	"business_icon",
98	"business_logo",
99	"customer_signature",
100	"dispute_evidence",
101	"document_provider_identity_document",
102	"finance_report_run",
103	"identity_document",
104	"identity_document_downloadable",
105	"pci_document",
106	"selfie",
107	"sigma_scheduled_query",
108	"tax_document_user_upload",
109	"terminal_reader_splashscreen",
110	]
111	]
112	"""	1✔
113	Filter queries by the file purpose. If you don't provide a purpose, the queries return unfiltered files.
114	"""
115	starting_after: NotRequired[str]	1✔
116	"""	1✔
117	A cursor for use in pagination. `starting_after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can include `starting_after=obj_foo` in order to fetch the next page of the list.
118	"""
119
120	class ListParamsCreated(TypedDict):	1✔
121	gt: NotRequired[int]	1✔
122	"""	1✔
123	Minimum value to filter by (exclusive)
124	"""
125	gte: NotRequired[int]	1✔
126	"""	1✔
127	Minimum value to filter by (inclusive)
128	"""
129	lt: NotRequired[int]	1✔
130	"""	1✔
131	Maximum value to filter by (exclusive)
132	"""
133	lte: NotRequired[int]	1✔
134	"""	1✔
135	Maximum value to filter by (inclusive)
136	"""
137
138	class RetrieveParams(RequestOptions):	1✔
139	expand: NotRequired[List[str]]	1✔
140	"""	1✔
141	Specifies which fields in the response should be expanded.
142	"""
143
144	created: int	1✔
145	"""	1✔
146	Time at which the object was created. Measured in seconds since the Unix epoch.
147	"""
148	expires_at: Optional[int]	1✔
149	"""	1✔
150	The file expires and isn't available at this time in epoch seconds.
151	"""
152	filename: Optional[str]	1✔
153	"""	1✔
154	The suitable name for saving the file to a filesystem.
155	"""
156	id: str	1✔
157	"""	1✔
158	Unique identifier for the object.
159	"""
160	links: Optional[ListObject["FileLink"]]	1✔
161	"""	1✔
162	A list of [file links](https://stripe.com/docs/api#file_links) that point at this file.
163	"""
164	object: Literal["file"]	1✔
165	"""	1✔
166	String representing the object's type. Objects of the same type share the same value.
167	"""
168	purpose: Literal[	1✔
169	"account_requirement",
170	"additional_verification",
171	"business_icon",
172	"business_logo",
173	"customer_signature",
174	"dispute_evidence",
175	"document_provider_identity_document",
176	"finance_report_run",
177	"identity_document",
178	"identity_document_downloadable",
179	"pci_document",
180	"selfie",
181	"sigma_scheduled_query",
182	"tax_document_user_upload",
183	"terminal_reader_splashscreen",
184	]
185	"""	1✔
186	The [purpose](https://stripe.com/docs/file-upload#uploading-a-file) of the uploaded file.
187	"""
188	size: int	1✔
189	"""	1✔
190	The size of the file object in bytes.
191	"""
192	title: Optional[str]	1✔
193	"""	1✔
194	A suitable title for the document.
195	"""
196	type: Optional[str]	1✔
197	"""	1✔
198	The returned file type (for example, `csv`, `pdf`, `jpg`, or `png`).
199	"""
200	url: Optional[str]	1✔
201	"""	1✔
202	Use your live secret API key to download the file from this URL.
203	"""
204
205	@classmethod	1✔
206	def create(cls, **params: Unpack["File.CreateParams"]) -> "File":	1✔
207	"""
208	To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.
209
210	All of Stripe's officially supported Client libraries support sending multipart/form-data.
211	"""
212	return cast(	1✔
213	"File",
214	cls._static_request(
215	"post",
216	cls.class_url(),
217	params=params,
218	base_address="files",
219	api_mode="V1FILES",
220	),
221	)
222
223	@classmethod	1✔
224	async def create_async(	1✔
225	cls, **params: Unpack["File.CreateParams"]
226	) -> "File":
227	"""
228	To upload a file to Stripe, you need to send a request of type multipart/form-data. Include the file you want to upload in the request, and the parameters for creating a file.
229
230	All of Stripe's officially supported Client libraries support sending multipart/form-data.
231	"""
232	return cast(	1✔
233	"File",
234	await cls._static_request_async(
235	"post",
236	cls.class_url(),
237	params=params,
238	base_address="files",
239	api_mode="V1FILES",
240	),
241	)
242
243	@classmethod	1✔
244	def list(cls, **params: Unpack["File.ListParams"]) -> ListObject["File"]:	1✔
245	"""
246	Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.
247	"""
248	result = cls._static_request(	1✔
249	"get",
250	cls.class_url(),
251	params=params,
252	)
253	if not isinstance(result, ListObject):	1!
UNCOV 254	raise TypeError(	×
255	"Expected list object from API, got %s"
256	% (type(result).__name__)
257	)
258
259	return result	1✔
260
261	@classmethod	1✔
262	async def list_async(	1✔
263	cls, **params: Unpack["File.ListParams"]
264	) -> ListObject["File"]:
265	"""
266	Returns a list of the files that your account has access to. Stripe sorts and returns the files by their creation dates, placing the most recently created files at the top.
267	"""
268	result = await cls._static_request_async(	1✔
269	"get",
270	cls.class_url(),
271	params=params,
272	)
273	if not isinstance(result, ListObject):	1!
UNCOV 274	raise TypeError(	×
275	"Expected list object from API, got %s"
276	% (type(result).__name__)
277	)
278
279	return result	1✔
280
281	@classmethod	1✔
282	def retrieve(	1✔
283	cls, id: str, **params: Unpack["File.RetrieveParams"]
284	) -> "File":
285	"""
286	Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to [access file contents](https://stripe.com/docs/file-upload#download-file-contents).
287	"""
288	instance = cls(id, **params)	1✔
289	instance.refresh()	1✔
290	return instance	1✔
291
292	@classmethod	1✔
293	async def retrieve_async(	1✔
294	cls, id: str, **params: Unpack["File.RetrieveParams"]
295	) -> "File":
296	"""
297	Retrieves the details of an existing file object. After you supply a unique file ID, Stripe returns the corresponding file object. Learn how to [access file contents](https://stripe.com/docs/file-upload#download-file-contents).
298	"""
299	instance = cls(id, **params)	1✔
300	await instance.refresh_async()	1✔
301	return instance	1✔
302
303	# This resource can have two different object names. In latter API
304	# versions, only `file` is used, but since stripe-python may be used with
305	# any API version, we need to support deserializing the older
306	# `file_upload` object into the same class.
307	OBJECT_NAME_ALT = "file_upload"	1✔
308
309	@classmethod	1✔
310	def class_url(cls):	1✔
311	return "/v1/files"	1✔
312
313
314	# For backwards compatibility, the `File` class is aliased to `FileUpload`.
315	FileUpload = File	1✔

stripe / stripe-python / 9067377560

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous