Documentation¶

The documentation page lists out all of the relevant classes and functions for interacting with the Sample Programs repo.

subete¶

The subete module contains all the classes need to represent the Sample Programs repo. This module was designed with the intent of creating read-only objects that fully represent the underlying repo. Ideally, classes that make use of these objects should not need to know how they were generated. For example, we do not want users to poke around the source directory that was used to generate these files. As a result, users should make use of the public methods only.

subete.load(source_dir: Optional[str] = None) → subete.repo.Repo¶

Loads the Sample Programs repo as a Repo object. This is a convenience function which can be used to quickly generate an instance of the Sample Programs repo.

Assuming subete is imported, here’s how you would use this function:

repo = subete.load()

Optionally, you can also provide a source directory which bypasses the need for git on your system:

repo = subete.load(source_dir="path/to/sample-programs/archive")

Returns: the Sample Programs repo as a Repo object

class subete.repo.LanguageCollection(name: str, path: str, file_list: List[str])¶

Bases: object

An object representing a collection of sample programs files for a particular programming language.

Parameters

name – the name of the language (e.g., python)
path – the path of the language (e.g., …/archive/p/python/)
file_list – the list of files in language collection

has_testinfo() → bool¶

Retrieves the state of the testinfo file. Helpful when trying to figure out if this language has a testinfo file.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

state: bool = language.has_testinfo()

Returns: True if a test info file exists; False otherwise

lang_docs_url() → str¶

Retrieves the URL to the language documentation. The language URL is assumed to exist and therefore not validated. The language documentation URL is in the following form:

https://sample-programs.therenegadecoder.com/languages/{lang}/

For example, here is a link to the Python documentation.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

link: str = language.lang_docs_url() 

Returns: the language documentation URL as a string

readme() → Optional[str]¶

Retrieves the README contents. README contents are in the form of a markdown string.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

contents: str = language.readme()

Returns: the README contents as a string

sample_programs() → List[subete.repo.SampleProgram]¶

Retrieves the list of sample programs associated with this language.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

programs: List[SampleProgram] = language.sample_programs()

Returns: the list of sample programs

testinfo() → Optional[dict]¶

Retrieves the test data from the testinfo file. The YAML data is loaded into a Python dictionary.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

data: dict = language.testinfo()

Returns: the test info data as a dictionary

testinfo_url() → str¶

Retrieves the URL to the testinfo file for this language on GitHub. The testinfo URL is assumed to exist and therefore not validated. The testinfo URL is in the following form:

https://github.com/TheRenegadeCoder/sample-programs/blob/main/archive/{letter}/{lang}/testinfo.yml

For example, here is a link to the Python testinfo file.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

link: str = language.testinfo_url()  

Returns: the testinfo URL as a string

total_line_count() → int¶

Retrieves the total line count of the language collection. Line count is computed from the sample programs only and does not include lines of code in testinfo or README files.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

lines: int = language.total_line_count() 

Returns: the total line count of the language collection as an int

total_programs() → int¶

Retrieves the total number of sample programs in the language collection.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

programs_count: int = language.total_programs()

Returns: the number of sample programs as an int

total_size() → int¶

Retrieves the total byte size of the sample programs in the language collection. Size is computed from the size of all sample programs and is not computed from the testinfo or README files.

Assuming you have a LanguageCollection object called language, here’s how you would use this method:

size: int = language.total_size()

Returns: the total byte size of the language collection as an int

class subete.repo.Repo(source_dir: Optional[str] = None)¶

Bases: object

An object representing the Sample Programs repository.

Parameters: source_dir – the location of the repo archive (e.g., C://…/sample-programs/archive)

get_languages_by_letter(letter: str) → List[subete.repo.LanguageCollection]¶

A convenience method for retrieving all language collections that start with a particular letter.

Assuming you have a Repo object called repo, here’s how you would use this method:

langs: List[LanguageCollection] = repo.get_languages_by_letter("p")

Parameters: letter – a character to search by
Returns: a list of language collections where the language starts with the provided letter

get_sorted_language_letters() → List[str]¶

A convenience method which generates a list of sorted letters from the sample programs archive. This will return a list of letters that match the directory structure of the archive.

Assuming you have a Repo object called repo, here’s how you would use this method:

letters: List[str] = repo.get_sorted_language_letters()

Returns: a sorted list of letters

language_collections() → List[subete.repo.LanguageCollection]¶

Retrieves the list of language collections in the Sample Programs repo.

Assuming you have a Repo object called repo, here’s how you would use this method:

languages: List[LanguageCollection] = repo.language_collections()

Returns: the list of the language collections

total_programs() → int¶

Retrieves the total number of programs in the sample programs repo. This total does not include any additional files such as README or testinfo files.

Assuming you have a Repo object called repo, here’s how you would use this method:

count: int = repo.total_programs()

Returns: the total number of programs as an int

total_tests() → int¶

Retrieves the total number of tested languages in the repo. This value is based on the number of testinfo files in the repo.

Assuming you have a Repo object called repo, here’s how you would use this method:

count: int = repo.total_tests()

Returns: the total number of tested languages as an int

class subete.repo.SampleProgram(path: str, file_name: str, language: str)¶

Bases: object

An object representing a sample program in the repo.

Parameters

path – the path to the sample program without the file name
file_name – the name of the file including the extension
language – the programming language of this sample program

article_issue_query_url() → str¶

Retrieves the URL to the article issue query for this sample program. The article issue query URL is guaranteed to be a valid search query on GitHub, but it is not guaranteed to have any results. The issue query url is in the following form:

https://github.com//TheRenegadeCoder/sample-programs-website/issues?{query}"

For example, here is a link to the Hello World in Python query.

Assuming you have a SampleProgram object called program, here’s how you would use this method:

url: str = program.article_issue_query_url()

Returns: the issue query URL as a string

code() → str¶

Retrieves the code for this sample program. To save space in memory, code is loaded from the source file on each invocation of this method. As a result, there may be an IO performance penalty if this function is used many times. It’s recommended to store the result of this function if it is used often.

Assuming you have a SampleProgram object called program, here’s how you would use this method:

code: str = program.code()

Returns: the code for the sample program as a string

documentation_url() → str¶

Retrieves the URL to the documentation for this sample program. Documentation URL is assumed to exist and therefore not validated. The documentation URL is in the following form:

https://sample-programs.therenegadecoder.com/projects/{project}/{lang}/

For example, here is a link to the Hello World in Python documentation.

Assuming you have a SampleProgram object called program, here’s how you would use this method:

url: str = program.documentation_url()

Returns: the documentation URL as a string

language() → str¶

Retrieves the language name for this sample program. Language name is generated from a call to str() for the source LanguageCollection.

Assuming you have a SampleProgram object called program, here’s how you would use this method:

name: str = program.language()

Returns: the language of the sample program as a string

line_count() → int¶

Retrieves the number of lines in the sample program.

Assuming you have a SampleProgram object called program, here’s how you would use this method:

code: int = program.line_count()

Returns: the number of lines for the sample program as an integer

requirements_url() → str¶

Retrieves the URL to the requirements documentation for this sample program. Requirements URL is assumed to exist and therefore not validated. The requirements documentation URL is in the following form:

https://sample-programs.therenegadecoder.com/projects/{project}/

For example, here is a link to the Hello World documentation.

Assuming you have a SampleProgram object called program, here’s how you would use this method:

url: str = program.requirements_url()

Returns: the requirments URL as a string

size() → int¶

Retrieves the size of the sample program in bytes.

Assuming you have a SampleProgram object called program, here’s how you would use this method:

size: int = program.size()

Returns: the size of the sample program as an integer