|
1 | 1 | # Lithic Python API library |
2 | 2 |
|
3 | | -> **Migration Guide** |
4 | | -> |
5 | | -> We've made some major improvements to how you pass arguments to methods which will require migrating your existing code. |
6 | | -> |
7 | | -> If you want to migrate to the new patterns incrementally you can do so by installing `v0.5.0`. This release contains both |
8 | | -> the new and old patterns with a backwards compatibility layer. |
9 | | -> |
10 | | -> You can find a guide to migrating in [this document](#migration-guide). |
11 | | -
|
12 | 3 | [](https://pypi.org/project/lithic/) |
13 | 4 |
|
14 | 5 | The Lithic Python library provides convenient access to the Lithic REST API from any Python 3.7+ |
@@ -343,178 +334,6 @@ client = Lithic( |
343 | 334 |
|
344 | 335 | By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting. |
345 | 336 |
|
346 | | -# Migration guide |
347 | | - |
348 | | -This section outlines the features that were deprecated in `v0.5.0`, and subsequently removed in `v0.6.0` and how to migrate your code. |
349 | | - |
350 | | -## Breaking changes |
351 | | - |
352 | | -### TypedDict → keyword arguments |
353 | | - |
354 | | -The way you pass arguments to methods has been changed from a single `TypedDict` to individual arguments. For example, this snippet: |
355 | | - |
356 | | -```python |
357 | | -card = await client.cards.create({"type": "VIRTUAL"}) |
358 | | -``` |
359 | | - |
360 | | -Now becomes: |
361 | | - |
362 | | -```python |
363 | | -card = await client.cards.create(type="VIRTUAL") |
364 | | -``` |
365 | | - |
366 | | -#### Migrating |
367 | | - |
368 | | -The easiest way to make your code compatible with this change is to add `**{`, for example: |
369 | | - |
370 | | -```diff |
371 | | -- card = await client.cards.create({'type': 'VIRTUAL'}) |
372 | | -+ card = await client.cards.create(**{'type': 'VIRTUAL'}) |
373 | | -``` |
374 | | - |
375 | | -However, it is highly recommended to completely switch to explicit keyword arguments: |
376 | | - |
377 | | -```diff |
378 | | -- card = await client.cards.create({'type': 'VIRTUAL'}) |
379 | | -+ card = await client.cards.create(type='VIRTUAL') |
380 | | -``` |
381 | | - |
382 | | -### Named path arguments |
383 | | - |
384 | | -All but the last path parameter must now be passed as named arguments instead of positional arguments, for example, for a method that calls the endpoint `/account_holders/{account_holder_token}/documents/{document_token}` you would've been able to call the method like this: |
385 | | - |
386 | | -```python |
387 | | -card = await client.account_holders.retrieve( |
388 | | - "account_holder_token", "my_document_token" |
389 | | -) |
390 | | -``` |
391 | | - |
392 | | -But now you must call the method like this: |
393 | | - |
394 | | -```python |
395 | | -card = await client.account_holders.retrieve( |
396 | | - "my_document_token", account_holder_token="account_holder_token" |
397 | | -) |
398 | | -``` |
399 | | - |
400 | | -If you have type checking enabled in your IDE it will tell you which parts of your code need to be updated. |
401 | | - |
402 | | -### Request options |
403 | | - |
404 | | -You used to be able to set request options on a per-method basis, now you can only set them on the client. There are two methods that you can use to make this easy, `with_options` and `copy`. |
405 | | - |
406 | | -If you need to make multiple requests with changed options, you can use `.copy()` to get a new client object with those options. This can be useful if you need to set a custom header for multiple requests, for example: |
407 | | - |
408 | | -```python |
409 | | -copied = client.copy(default_headers={"X-My-Header": "Foo"}) |
410 | | -card = await copied.cards.create(type="VIRTUAL") |
411 | | -await copied.cards.provision(card.token, digital_wallet="GOOGLE_PAY") |
412 | | -``` |
413 | | - |
414 | | -If you just need to override one of the client options for one request, you can use `.with_options()`, for example: |
415 | | - |
416 | | -```python |
417 | | -await client.with_options(timeout=None).cards.create(type="VIRTUAL") |
418 | | -``` |
419 | | - |
420 | | -It should be noted that the `.with_options()` method is simply an alias to `.copy()`, you can use them interchangeably. |
421 | | - |
422 | | -You can pass nearly every argument that is supported by the Client `__init__` method to the `.copy()` method, except for `proxies` and `transport`. |
423 | | - |
424 | | -```python |
425 | | -copied = client.copy( |
426 | | - api_key="...", |
427 | | - environment="sandbox", |
428 | | - timeout=httpx.Timeout(read=10), |
429 | | - max_retries=5, |
430 | | - default_headers={ |
431 | | - "X-My-Header": "value", |
432 | | - }, |
433 | | - default_query={ |
434 | | - "my_default_param": "value", |
435 | | - }, |
436 | | -) |
437 | | -``` |
438 | | - |
439 | | -## New features |
440 | | - |
441 | | -### Pass custom headers |
442 | | - |
443 | | -If you need to add additional headers to a request you can easily do so with the `extra_headers` argument: |
444 | | - |
445 | | -```python |
446 | | -card = await client.cards.create( |
447 | | - type="VIRTUAL", |
448 | | - extra_headers={ |
449 | | - "X-Foo": "my header", |
450 | | - }, |
451 | | -) |
452 | | -``` |
453 | | - |
454 | | -### Pass custom JSON properties |
455 | | - |
456 | | -You can add additional properties to the JSON request body that are not included directly in the method definition through the `extra_body` argument. This can be useful when there are in new properties in the API that are in beta and aren't in the SDK yet. |
457 | | - |
458 | | -```python |
459 | | -card = await client.cards.create( |
460 | | - type="VIRTUAL", |
461 | | - extra_body={ |
462 | | - "special_prop": "foo", |
463 | | - }, |
464 | | -) |
465 | | -# sends this to the API: |
466 | | -# {"type": "VIRTUAL", "special_prop": "foo"} |
467 | | -``` |
468 | | - |
469 | | -### Pass custom query parameters |
470 | | - |
471 | | -You can add additional query parameters that aren't specified in the method definition through the `extra_query` argument. This can be useful when there are any new/beta query parameters that are not yet in the SDK. |
472 | | - |
473 | | -```python |
474 | | -card = await client.cards.create( |
475 | | - type="VIRTUAL", |
476 | | - extra_query={ |
477 | | - "special_param": "bar", |
478 | | - }, |
479 | | -) |
480 | | -# makes the request to this URL: |
481 | | -# https://api.lithic.com/v1/cards?special_param=bar |
482 | | -``` |
483 | | - |
484 | | -## Rich `date` and `datetime` types |
485 | | - |
486 | | -We've improved the types for response fields / request params that correspond to `date` or `datetime` values! |
487 | | - |
488 | | -Previously they were just raw strings but now response fields will be instances of `date` or `datetime`. |
489 | | - |
490 | | -This means that if you're working with these fields and parsing them into `datetime` instances manually you will have to remove |
491 | | -any code that performs said parsing. |
492 | | - |
493 | | -```diff |
494 | | -card = client.cards.retrieve('<token>') |
495 | | -- created = datetime.fromisoformat(card.created_at) |
496 | | -+ created = card.created_at |
497 | | -print(created.month) |
498 | | -``` |
499 | | - |
500 | | -For request params you can continue to pass in strings if you want to use a datetime library other than the standard library version but if you |
501 | | -were writing code that looked like this: |
502 | | - |
503 | | -```py |
504 | | -dt = datetime(...) |
505 | | -for card in client.cards.list(begin=dt.isoformat()): |
506 | | - ... |
507 | | -``` |
508 | | - |
509 | | -You can remove the explicit call to `isoformat`! |
510 | | - |
511 | | -```diff |
512 | | -dt = datetime(...) |
513 | | -- for card in client.cards.list(begin=dt.isoformat()): |
514 | | -+ for card in client.cards.list(begin=dt): |
515 | | - ... |
516 | | -``` |
517 | | - |
518 | 337 | ## Versioning |
519 | 338 |
|
520 | 339 | This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions: |
|
0 commit comments