PythonTop40 Project Documentation v 0.1.6¶
Contents¶
- Installation
- Exploring the Demo Code
- Our example program
- Importing the PythonTop40 module
- Creating a Top40 instance
- Retrieving the Top40 albums
- The format of the returned data
- Accessing the information within each chart entry
- Printing extra information about the chart entry
- Formatting the output columns
- Accessing the change information
- Printing the change information
- Some finishing touches
- PythonTop40 top40
- PythonTop40 errors
- Change Log for PythonTop40
- v0.1.6 3rd January 2105
- v0.1.5 29th December 2014
- v0.1.4 29th December 2014
- v0.1.3 29th December 2014
- v0.1.2 29th December 2014
- v0.1.1 14th December 2014
- v0.1.0 13th December 2014
- v0.1.0.dev9 - 12th December 2014
- v0.1.0.dev8 - 12th December 2014
- v0.1.0.dev7 - 11th December 2014
- v0.1.0.dev6 - 11th December 2014
- v0.1.0.dev5 - 8th December 2014
- v0.1.0.dev4 - 6th December 2014
- v0.1.0.dev3 - 6th December 2014
- v0.1.0.dev2 - 6th December 2014
- V0.1.0.dev1 - 4th December 2014
PythonTop40¶
The PythonTop40 library is designed to be used in UK schools to provide students with access to data that describes the UK Top 40 singles and albums.
This is part of a wider initiative that I’m referring to as Code-Further. The hope is that by providing simple interfaces to information that is relevant to students, they will be able to relate to the data and imagine more ways in which they could consume and use it in their code - and hopefully Code-Further.
The data that PythonTop40 accesses is provided by the excellent work by @Ben Major and his UK Top 40 Charts API.
PythonTop40 is under active development visit this blog post for more information. and licensed under the Apache2 license, so feel free to contribute and report errors and suggestions.
Note
The PythonTop40 library is designed to be used in UK schools to provide programmatic access to data that describes the UK Top 40 singles and albums. The hope is that by providing simple interfaces to access information that students may have an interest in, they may be inspired to code-further. This documentation will therefore most likely be aimed at teachers and education professionals, who may not have a deep knowledge of Python.
Warning
PythonTop40 is currently designed to work with Python version 3. I have recently carried out some work to make it run on Python 2, but this does need to be more thoroughly tested that my current Nose tests allow. If you encounter any issues, or you’d like to submit a pull request, please contact me on BitBucket.
Usage¶
PythonTop40 exposes a very simple API to developers. It is accessed by importing the Top40 class into your module and creating an instance of this class, like so:
from pythontop40 import Top40
top40 = Top40()
The top40 instance exposes a number of properties to the programmer. These include:
The example code below shows how you can use one of these properties to get a list of the current Top 40 albums.:
from pythontop40 import Top40
top40 = Top40()
albums = top40.albums
for album in albums:
print(
album.position,
album.title,
"BY",
album.artist
)
This short program uses the albums property of the Top40 class to obtain the Python list of the current Top 40 UK albums. It then loops through this list, and at each iteration of the loop the variable album is set to the next album entry in the list.
A print() function then prints the position, title and artist attributes of the album entry resulting in something like this::
1 Never Been Better BY Olly Murs
2 X BY Ed Sheeran
3 FOUR BY One Direction
4 In The Lonely Hour BY Sam Smith
5 The Endless River BY Pink Floyd
.
.
.
40 The London Sessions BY Mary J. Blige
I hope it’s pretty clear what is going on, but a more detailed discussion of what the program does on can be found here.
Features¶
PythonTop40 provides:
- a list of the current Top 40 UK singles using the singles property of the Top40 class.
- a list of the current Top 40 UK albums using the albums property of the Top40 class.
- a chart object relating to either singles or albums. The chart object contains the:
- PythonTop40 will also cache the results, so that once a result type (singles or albums) has been retrieved from
the remote server, it will be returned on subsequent requests from the cache without refreshing from the remote
server.
- PythonTop40 will use a persistent cache by default. This should ensure that the remote server is not hammered with requests when the data is unlikely to change too frequently. The default duration for the cache is 3600 seconds (1 hour). Unlike the in-memory cache, the persistent cache will survive after the Python interpreter run session ends. The duration can be changed by passing a cache_duration value to the Top40 constructor. Using a value of None for cache_duration will disable the persistent cache and rely on the in-memory cache only.
- The cache can be reset using the reset_cache() method, so that the next request for albums or singles information will be forced to obtain it by connecting to the remote server.
Installation¶
PythonTop40 can be found on the Python Package Index PyPi here. It can be installed using pip, like so.
pip install pythontop40
Documentation¶
The documentation for PythonTop40 can be found on the ReadTheDocs site.
API - Application Programming Interface¶
The full documentation of the classes and functions that make up PythonTop40 can be found here, and the errors and exceptions can be found here.
Tests¶
To run the PythonTop40 test suite, you should install the test and development requirements and then run nosetests.
$ pip install -r dev-requirements.txt
$ nosetests tests