|
| 1 | +.. _intro-tutorial: |
| 2 | + |
| 3 | +.. role:: red |
| 4 | + |
| 5 | +.. raw:: html |
| 6 | + |
| 7 | + <style> .red {color:red} </style> |
| 8 | + |
| 9 | +========================== |
| 10 | +Restcountries cli Tutorial |
| 11 | +========================== |
| 12 | + |
| 13 | +Once you have install the package you can instantiate a client and get the data for the |
| 14 | +countries. |
| 15 | + |
| 16 | +.. code-block:: python |
| 17 | +
|
| 18 | + from restcountries_cli import RestCountriesCli |
| 19 | +
|
| 20 | + client = RestCountriesCli() |
| 21 | + countries = client.all() |
| 22 | +
|
| 23 | +If you want for example information about a single country you can use the country_name method. |
| 24 | + |
| 25 | +.. code-block:: python |
| 26 | +
|
| 27 | + from restcountries_cli import RestCountriesCli |
| 28 | +
|
| 29 | + client = RestCountriesCli() |
| 30 | + country = client.all() # This will call the API |
| 31 | + country = client.all() # This will not call the API |
| 32 | +
|
| 33 | +:red:`TODO` More methods will be add in the future to query the API with other values. |
| 34 | + |
| 35 | +Cached API calls |
| 36 | +---------------- |
| 37 | + |
| 38 | +All the calls to the restcountries API by default are cached in a sqlite database. However this cache can be configured. |
| 39 | + |
| 40 | +To start you can avoid this API cache and call each time you run the methods of the cli by setting the parameter ``cached_session`` to False when instantiating the client: |
| 41 | + |
| 42 | +.. code-block:: python |
| 43 | +
|
| 44 | + from restcountries_cli import RestCountriesCli |
| 45 | +
|
| 46 | + client = RestCountriesCli(cached_session=False) |
| 47 | + country = client.all() # This will call the API |
| 48 | + country = client.all() # This will also call the API |
| 49 | +
|
| 50 | +Also you can specify the `sqlite` file name if you want by changing the ``cache_name`` parameter. By default it will create a file which name will be a random uuid. |
| 51 | + |
| 52 | +But this means that I have to clean the file each time I run RestCountriesCli? NO! Once you destroy the client object it will automatically clean the cache by removing that file. So you can use this parameter, but it was designed to be used for testing purposes. |
| 53 | + |
| 54 | +.. code-block:: python |
| 55 | +
|
| 56 | + from restcountries_cli import RestCountriesCli |
| 57 | +
|
| 58 | + client = RestCountriesCli(cache_name="test") |
| 59 | + country = client.country_name("spain") # This will add an entry in the test.sqlite file in the project root folder |
| 60 | +
|
| 61 | +You can also force to restart the cache by calling the method ``refresh_cached_session``. |
| 62 | + |
| 63 | +.. code-block:: python |
| 64 | +
|
| 65 | + from restcountries_cli import RestCountriesCli |
| 66 | +
|
| 67 | + client = RestCountriesCli() |
| 68 | + country = client.all() # This will call the API |
| 69 | + client.refresh_cached_session() |
| 70 | + country = client.all() # This will call the API again |
| 71 | +
|
| 72 | +Data saved in the cli |
| 73 | +--------------------- |
| 74 | + |
| 75 | +Ok so imagine that you get the data of all the countries by calling the ``all`` method of the client. Now you want to know the info of a concrete country. You can search it in the list returned by the ``all`` method oooooor, you can just get the country by it's name for example. |
| 76 | + |
| 77 | +This second call will not call the API, even if your session is not cached. This is because internally all the countries given by the API are saved in a list inside the cli called ``countries``. So, if the country you are looking for is inside this list, the call is not needed. |
| 78 | + |
| 79 | +.. code-block:: python |
| 80 | +
|
| 81 | + from restcountries_cli import RestCountriesCli |
| 82 | +
|
| 83 | + client = RestCountriesCli() |
| 84 | + country = client.all() # This will call the API and save the countries parsed in client.countries |
| 85 | + country = client.country_name("spain") # This will not call the API again as this country is inside client.countries from the previous call |
| 86 | +
|
| 87 | +This will even work for single countries |
| 88 | + |
| 89 | +.. code-block:: python |
| 90 | +
|
| 91 | + from restcountries_cli import RestCountriesCli |
| 92 | +
|
| 93 | + client = RestCountriesCli() |
| 94 | + country = client.country_name("spain") # This will call the API and save the country in the client countries list |
| 95 | + country = client.country_name("spain") # This will not call the API again as this country is inside client.countries from the previous call |
| 96 | +
|
| 97 | +But you can force the query, I mean, this is not usual (as it was designed for testing purposes), but you can: |
| 98 | + |
| 99 | +.. code-block:: python |
| 100 | +
|
| 101 | + from restcountries_cli import RestCountriesCli |
| 102 | +
|
| 103 | + client = RestCountriesCli(cached_session=False) |
| 104 | + country = client.country_name("spain") # This will call the API |
| 105 | + country = client.country_name("spain", force_query=True) # This will also call the API, as the cli has not cache and you forced to call again the endpoint |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?v=4&size=40){kind=avatar}
0 commit comments