diff --git a/codegen/pkg/builder/out.go b/codegen/pkg/builder/out.go index 1ff27b41..068f2b1f 100644 --- a/codegen/pkg/builder/out.go +++ b/codegen/pkg/builder/out.go @@ -100,12 +100,13 @@ func (b *Builder) generateResourceIndex(tagName string, resourceTypes []string) } type resourceTemplateData struct { - PackageName string - TypeNames []string - Params []Writable - Service string - Methods []*Method - UsesSecret bool + PackageName string + TypeNames []string + Params []Writable + Service string + Methods []*Method + UsesSecret bool + TagDescription string } func (b *Builder) generateResourceFile(tagName string, paths *v3.Paths) ([]string, error) { @@ -139,12 +140,13 @@ func (b *Builder) generateResourceFile(tagName string, paths *v3.Paths) ([]strin serviceBuf := bytes.NewBuffer(nil) if err := b.templates.ExecuteTemplate(serviceBuf, "resource.py.tmpl", resourceTemplateData{ - PackageName: strcase.ToSnake(tag.Name), - TypeNames: typeNames, - Params: innerTypes, - Service: strcase.ToCamel(tag.Name), - Methods: methods, - UsesSecret: usesSecret, + PackageName: strcase.ToSnake(tag.Name), + TypeNames: typeNames, + Params: innerTypes, + Service: strcase.ToCamel(tag.Name), + Methods: methods, + UsesSecret: usesSecret, + TagDescription: strings.TrimSpace(tag.Description), }); err != nil { return nil, err } @@ -232,8 +234,9 @@ func (b *Builder) writeClientFile(fname string, tags []string) error { }() type resource struct { - Name string - Package string + Name string + Package string + ShortDocstring string } resources := make([]resource, 0, len(tags)) @@ -242,8 +245,9 @@ func (b *Builder) writeClientFile(fname string, tags []string) error { continue } resources = append(resources, resource{ - Name: strcase.ToCamel(tags[i]), - Package: strcase.ToSnake(tags[i]), + Name: strcase.ToCamel(tags[i]), + Package: strcase.ToSnake(tags[i]), + ShortDocstring: fmt.Sprintf("Access the %s API endpoints.", strcase.ToCamel(tags[i])), }) } diff --git a/codegen/templates/client.py.tmpl b/codegen/templates/client.py.tmpl index d9877687..9e5f8861 100644 --- a/codegen/templates/client.py.tmpl +++ b/codegen/templates/client.py.tmpl @@ -43,6 +43,7 @@ class Sumup(Resource): {{- range .Resources }} @property def {{ .Package }}(self) -> {{ .Name }}Resource: + """{{ .ShortDocstring }}""" from .{{ .Package }}.resource import {{ .Name }}Resource return {{ .Name }}Resource(self._client) @@ -71,6 +72,7 @@ class AsyncSumup(AsyncResource): {{- range .Resources }} @property def {{ .Package }}(self) -> Async{{ .Name }}Resource: + """{{ .ShortDocstring }}""" from .{{ .Package }}.resource import Async{{ .Name }}Resource return Async{{ .Name }}Resource(self._client) diff --git a/codegen/templates/resource.py.tmpl b/codegen/templates/resource.py.tmpl index 3e6d5f18..f1f334bf 100644 --- a/codegen/templates/resource.py.tmpl +++ b/codegen/templates/resource.py.tmpl @@ -1,4 +1,9 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +{{- with .TagDescription }} +""" +{{ . }} +""" +{{- end }} from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -21,6 +26,8 @@ import typing_extensions class {{.Service}}Resource(Resource): + """API resource for the {{.Service}} endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -69,6 +76,8 @@ class {{.Service}}Resource(Resource): {{end}} class Async{{.Service}}Resource(AsyncResource): + """Async API resource for the {{.Service}} endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/_client.py b/sumup/_client.py index b80e7b49..078f6ce2 100644 --- a/sumup/_client.py +++ b/sumup/_client.py @@ -52,66 +52,77 @@ def __init__( @property def checkouts(self) -> CheckoutsResource: + """Access the Checkouts API endpoints.""" from .checkouts.resource import CheckoutsResource return CheckoutsResource(self._client) @property def customers(self) -> CustomersResource: + """Access the Customers API endpoints.""" from .customers.resource import CustomersResource return CustomersResource(self._client) @property def members(self) -> MembersResource: + """Access the Members API endpoints.""" from .members.resource import MembersResource return MembersResource(self._client) @property def memberships(self) -> MembershipsResource: + """Access the Memberships API endpoints.""" from .memberships.resource import MembershipsResource return MembershipsResource(self._client) @property def merchants(self) -> MerchantsResource: + """Access the Merchants API endpoints.""" from .merchants.resource import MerchantsResource return MerchantsResource(self._client) @property def payouts(self) -> PayoutsResource: + """Access the Payouts API endpoints.""" from .payouts.resource import PayoutsResource return PayoutsResource(self._client) @property def readers(self) -> ReadersResource: + """Access the Readers API endpoints.""" from .readers.resource import ReadersResource return ReadersResource(self._client) @property def receipts(self) -> ReceiptsResource: + """Access the Receipts API endpoints.""" from .receipts.resource import ReceiptsResource return ReceiptsResource(self._client) @property def roles(self) -> RolesResource: + """Access the Roles API endpoints.""" from .roles.resource import RolesResource return RolesResource(self._client) @property def subaccounts(self) -> SubaccountsResource: + """Access the Subaccounts API endpoints.""" from .subaccounts.resource import SubaccountsResource return SubaccountsResource(self._client) @property def transactions(self) -> TransactionsResource: + """Access the Transactions API endpoints.""" from .transactions.resource import TransactionsResource return TransactionsResource(self._client) @@ -140,66 +151,77 @@ def __init__( @property def checkouts(self) -> AsyncCheckoutsResource: + """Access the Checkouts API endpoints.""" from .checkouts.resource import AsyncCheckoutsResource return AsyncCheckoutsResource(self._client) @property def customers(self) -> AsyncCustomersResource: + """Access the Customers API endpoints.""" from .customers.resource import AsyncCustomersResource return AsyncCustomersResource(self._client) @property def members(self) -> AsyncMembersResource: + """Access the Members API endpoints.""" from .members.resource import AsyncMembersResource return AsyncMembersResource(self._client) @property def memberships(self) -> AsyncMembershipsResource: + """Access the Memberships API endpoints.""" from .memberships.resource import AsyncMembershipsResource return AsyncMembershipsResource(self._client) @property def merchants(self) -> AsyncMerchantsResource: + """Access the Merchants API endpoints.""" from .merchants.resource import AsyncMerchantsResource return AsyncMerchantsResource(self._client) @property def payouts(self) -> AsyncPayoutsResource: + """Access the Payouts API endpoints.""" from .payouts.resource import AsyncPayoutsResource return AsyncPayoutsResource(self._client) @property def readers(self) -> AsyncReadersResource: + """Access the Readers API endpoints.""" from .readers.resource import AsyncReadersResource return AsyncReadersResource(self._client) @property def receipts(self) -> AsyncReceiptsResource: + """Access the Receipts API endpoints.""" from .receipts.resource import AsyncReceiptsResource return AsyncReceiptsResource(self._client) @property def roles(self) -> AsyncRolesResource: + """Access the Roles API endpoints.""" from .roles.resource import AsyncRolesResource return AsyncRolesResource(self._client) @property def subaccounts(self) -> AsyncSubaccountsResource: + """Access the Subaccounts API endpoints.""" from .subaccounts.resource import AsyncSubaccountsResource return AsyncSubaccountsResource(self._client) @property def transactions(self) -> AsyncTransactionsResource: + """Access the Transactions API endpoints.""" from .transactions.resource import AsyncTransactionsResource return AsyncTransactionsResource(self._client) diff --git a/sumup/checkouts/resource.py b/sumup/checkouts/resource.py index 7426874b..049fda24 100755 --- a/sumup/checkouts/resource.py +++ b/sumup/checkouts/resource.py @@ -1,4 +1,12 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Accept payments from your end users by adding the Checkouts model to your platform. +SumUp supports standard and single payment 3DS checkout flows. + +The Checkout model allows creating, listing, retrieving, processing and deactivating checkouts. +A payment is completed by creating a checkout and then processing the checkout. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -194,6 +202,8 @@ class GetPaymentMethods200Response(pydantic.BaseModel): class CheckoutsResource(Resource): + """API resource for the Checkouts endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -384,6 +394,8 @@ def deactivate(self, id: str, headers: typing.Optional[HeaderTypes] = None) -> C class AsyncCheckoutsResource(AsyncResource): + """Async API resource for the Checkouts endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/customers/resource.py b/sumup/customers/resource.py index bf6802e0..19691d9c 100755 --- a/sumup/customers/resource.py +++ b/sumup/customers/resource.py @@ -1,4 +1,11 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Allow your regular customers to save their information with the Customers model. +This will prevent re-entering payment instrument information for recurring payments on your platform. + +Depending on the needs you can allow, creating, listing or deactivating payment instruments & creating, retrieving and updating customers. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -46,6 +53,8 @@ class UpdateCustomerBody(pydantic.BaseModel): class CustomersResource(Resource): + """API resource for the Customers endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -219,6 +228,8 @@ def deactivate_payment_instrument( class AsyncCustomersResource(AsyncResource): + """Async API resource for the Customers endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/members/resource.py b/sumup/members/resource.py index f654912b..16e1905b 100755 --- a/sumup/members/resource.py +++ b/sumup/members/resource.py @@ -1,4 +1,8 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Endpoints to manage account members. Members are users that have membership within merchant accounts. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -139,6 +143,8 @@ class ListMerchantMembers200Response(pydantic.BaseModel): class MembersResource(Resource): + """API resource for the Members endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -278,6 +284,8 @@ def delete( class AsyncMembersResource(AsyncResource): + """Async API resource for the Members endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/memberships/resource.py b/sumup/memberships/resource.py index 63cddc3f..7eab945b 100755 --- a/sumup/memberships/resource.py +++ b/sumup/memberships/resource.py @@ -1,4 +1,8 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Endpoints to manage user's memberships. Memberships are used to connect the user to merchant accounts and to grant them access to the merchant's resources via roles. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -92,6 +96,8 @@ class ListMemberships200Response(pydantic.BaseModel): class MembershipsResource(Resource): + """API resource for the Memberships endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -127,6 +133,8 @@ def list( class AsyncMembershipsResource(AsyncResource): + """Async API resource for the Memberships endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/merchants/resource.py b/sumup/merchants/resource.py index 2f94e62d..4bbbbae7 100755 --- a/sumup/merchants/resource.py +++ b/sumup/merchants/resource.py @@ -1,4 +1,8 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Merchant account represents a single business entity at SumUp. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -37,6 +41,8 @@ class GetPersonParams(pydantic.BaseModel): class MerchantsResource(Resource): + """API resource for the Merchants endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -132,6 +138,8 @@ def get_person( class AsyncMerchantsResource(AsyncResource): + """Async API resource for the Merchants endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/payouts/resource.py b/sumup/payouts/resource.py index 0c931a2e..1391d1c9 100755 --- a/sumup/payouts/resource.py +++ b/sumup/payouts/resource.py @@ -1,4 +1,9 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +The Payouts model will allow you to track funds you’ve received from SumUp. +You can receive a detailed payouts list with information like dates, fees, references and statuses, using the `List payouts` endpoint. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -52,6 +57,8 @@ class ListPayoutsParams(pydantic.BaseModel): class PayoutsResource(Resource): + """API resource for the Payouts endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -119,6 +126,8 @@ def list_deprecated( class AsyncPayoutsResource(AsyncResource): + """Async API resource for the Payouts endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/readers/resource.py b/sumup/readers/resource.py index 12ed787a..d9e52e78 100755 --- a/sumup/readers/resource.py +++ b/sumup/readers/resource.py @@ -1,4 +1,8 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +A reader represents a device that accepts payments. You can use the SumUp Solo to accept in-person payments. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -237,6 +241,8 @@ class ListReaders200Response(pydantic.BaseModel): class ReadersResource(Resource): + """API resource for the Readers endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -527,6 +533,8 @@ def terminate_checkout( class AsyncReadersResource(AsyncResource): + """Async API resource for the Readers endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/receipts/resource.py b/sumup/receipts/resource.py index dfc92e60..90fe073d 100755 --- a/sumup/receipts/resource.py +++ b/sumup/receipts/resource.py @@ -1,4 +1,8 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +The Receipts model obtains receipt-like details for specific transactions. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -21,6 +25,8 @@ class GetReceiptParams(pydantic.BaseModel): class ReceiptsResource(Resource): + """API resource for the Receipts endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -63,6 +69,8 @@ def get( class AsyncReceiptsResource(AsyncResource): + """Async API resource for the Receipts endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/roles/resource.py b/sumup/roles/resource.py index e369bfb8..f58d5002 100755 --- a/sumup/roles/resource.py +++ b/sumup/roles/resource.py @@ -1,4 +1,8 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Endpoints to manage custom roles. Custom roles allow you to tailor roles from individual permissions to match your needs. Once created, you can assign your custom roles to your merchant account members using the memberships. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -67,6 +71,8 @@ class ListMerchantRoles200Response(pydantic.BaseModel): class RolesResource(Resource): + """API resource for the Roles endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -182,6 +188,8 @@ def update( class AsyncRolesResource(AsyncResource): + """Async API resource for the Roles endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/subaccounts/resource.py b/sumup/subaccounts/resource.py index da1feafd..0436f4e4 100755 --- a/sumup/subaccounts/resource.py +++ b/sumup/subaccounts/resource.py @@ -1,4 +1,8 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Endpoints for managing merchant sub-accounts (operators). +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -97,6 +101,8 @@ class ListSubAccountsParams(pydantic.BaseModel): class SubaccountsResource(Resource): + """API resource for the Subaccounts endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -212,6 +218,8 @@ def update_sub_account( class AsyncSubaccountsResource(AsyncResource): + """Async API resource for the Subaccounts endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client) diff --git a/sumup/transactions/resource.py b/sumup/transactions/resource.py index c650dc34..db8edaf4 100755 --- a/sumup/transactions/resource.py +++ b/sumup/transactions/resource.py @@ -1,4 +1,9 @@ # Code generated by `py-sdk-gen`. DO NOT EDIT. +""" +Retrieve details for a specific transaction by it’s `id` +or any other required query parameter, or list all transactions related to the merchant account. +""" + from __future__ import annotations from .._service import Resource, AsyncResource, HeaderTypes from .._exceptions import APIError @@ -170,6 +175,8 @@ class ListTransactions200Response(pydantic.BaseModel): class TransactionsResource(Resource): + """API resource for the Transactions endpoints.""" + def __init__(self, client: httpx.Client) -> None: super().__init__(client) @@ -335,6 +342,8 @@ def list_deprecated( class AsyncTransactionsResource(AsyncResource): + """Async API resource for the Transactions endpoints.""" + def __init__(self, client: httpx.AsyncClient) -> None: super().__init__(client)