Addressed Several Issues Related to the 0.5.0 Release (#25)

* Removed print statement

* Simplified testin

* Documenting the subscriptable behavior

* Cleaned up documentation

* Fixed documentation for sample programs method

* Added the pathlike name function

* Updated README

* Adding logs

* Added various logs

* Updated changelog

* Updated minor version

README.md

@@ -1,8 +1,9 @@
-# subete
-
-The plan for this repo is to extract the repo traversal utilities
-from the sample-programs-docs-generator. I really like this as 
-a way of providing a Python library which interfaces with the
-Sample Programs repo. I can already see this being useful for
-our own internal documentation but also useful for anyone who
-just wants to explore code in a bunch of different languages. 
+# Subete
+
+Subete is a Python library for interacting with the Sample Programs
+repository. It works by cloning the repository and analyzing its
+contents. It is currently in its alpha form, but you can already
+see it being used in various Sample Programs projects. 
+
+If you're interested in exploring the repo programatically,
+check out the [official documentation](https://subete.therenegadecoder.com). 

docs/changelog.rst

@@ -1,6 +1,17 @@
 Changelog
 =========
 
+* v0.5.0
+    * Updated README to indicate alpha stage of project
+    * Added logging support
+    * Added method of retrieving pathlike name of LanguageCollection
+    * Fixed type hinting of sample_programs() method
+    * Removed extraneous print statement
+    * Made Repo and LanguageCollection subscriptable
+
+* v0.4.1
+    * Fixed an issue where generated links were broken
+
 * v0.4.0
     * Forced a convention for LanguageCollection and SampleProgram as strings
     * Added test URL functionality to LanguageCollection

setup.py

@@ -12,8 +12,8 @@
     long_description = fh.read()
 
 MAJOR = 0
-MINOR = 4
-PATCH = 1
+MINOR = 5
+PATCH = 0
 
 name = "subete"
 version = f"{MAJOR}.{MINOR}"

subete/repo.py

@@ -204,8 +204,8 @@ def _normalize_program_name(self) -> str:
             url = stem.replace("_", "-").lower()
         else:
             # TODO: this is brutal. At some point, we should loop in the glotter test file.
-            url = re.sub(
-                '((?<=[a-z])[A-Z0-9]|(?!^)[A-Z](?=[a-z]))', r'-\1', stem).lower()
+            url = re.sub('((?<=[a-z])[A-Z0-9]|(?!^)[A-Z](?=[a-z]))', r'-\1', stem).lower()
+        logger.info(f"Constructed a normalized form of the program {url}")
         return url
 
     def _generate_requirements_url(self) -> str:
@@ -290,6 +290,26 @@ def __str__(self) -> str:
         else:
             return " ".join(tokens).title()
 
+    def __getitem__(self, program) -> str:
+        """
+        Makes a language collection subscriptable. In this case, the subscript 
+        retrieves a sample program. 
+
+        :param program: the name of the program to lookup
+        :return: the sample program by name
+        """
+        return self._sample_programs[program]
+
+    def pathlike_name(self):
+        """
+        Retrieves a pathlike name for this language. For example,
+        instead of returning C# it would return c-sharp. Names
+        are based on the folder names in the Sample Programs repo.
+
+        :return: the pathlike name of this programming language
+        """
+        return self._name
+
     def testinfo(self) -> Optional[dict]:
         """
         Retrieves the test data from the testinfo file. The YAML data
@@ -337,16 +357,17 @@ def readme(self) -> Optional[str]:
         if self._read_me_path:
             return Path(self._read_me_path).read_text()
 
-    def sample_programs(self) -> List[SampleProgram]:
+    def sample_programs(self) -> Dict[str, SampleProgram]:
         """
-        Retrieves the list of sample programs associated with this language.
+        Retrieves the dictionary of sample programs associated with this language.
+        Each sample program can be looked up by name (e.g., Hello World)
 
         Assuming you have a LanguageCollection object called language, 
         here's how you would use this method::
 
-            programs: List[SampleProgram] = language.sample_programs()
+            programs: Dict[SampleProgram] = language.sample_programs()
 
-        :return: the list of sample programs
+        :return: the dictionary of sample programs
         """
         return self._sample_programs
 
@@ -445,8 +466,8 @@ def _collect_sample_programs(self) -> Dict[str, SampleProgram]:
             file_ext = file_ext.lower()
             if file_ext not in (".md", "", ".yml"):
                 program = SampleProgram(self._path, file, str(self))
-                print(program)
                 sample_programs[program.project()] = program
+                logger.debug(f"New sample program collected: {program}")
         sample_programs = dict(sorted(sample_programs.items()))
         return sample_programs
 
@@ -458,6 +479,7 @@ def _collect_test_file(self) -> Optional[str]:
         :return: the path to a test info file
         """
         if "testinfo.yml" in self._file_list:
+            logger.debug(f"New test file collected for {self}")
             return os.path.join(self._path, "testinfo.yml")
 
     def _collect_readme(self) -> Optional[str]:
@@ -468,6 +490,7 @@ def _collect_readme(self) -> Optional[str]:
         :return: the path to a readme
         """
         if "README.md" in self._file_list:
+            logger.debug(f"New README collected for {self}")
             return os.path.join(self._path, "README.md")
 
 
@@ -485,6 +508,16 @@ def __init__(self, source_dir: Optional[str] = None) -> None:
         self._total_snippets: int = sum(x.total_programs() for _, x in self._languages.items())
         self._total_tests: int = sum(1 for _, x in self._languages.items() if x.has_testinfo())
 
+    def __getitem__(self, language) -> LanguageCollection:
+        """
+        Makes a repo subscriptable. In this case, the subscript retrieves a 
+        language collection. 
+
+        :param language: the name of the language to lookup
+        :return: the language collection by name
+        """
+        return self._languages[language]
+
     def language_collections(self) -> Dict[str, LanguageCollection]:
         """
         Retrieves the list of language names mapped to their language collections in 
@@ -575,6 +608,7 @@ def _collect_languages(self) -> Dict[str, LanguageCollection]:
             if not directories:
                 language = LanguageCollection(os.path.basename(root), root, files)
                 languages[str(language)] = language
+                logger.debug(f"New language collected: {language}")
         languages = dict(sorted(languages.items()))
         return languages
 
@@ -586,7 +620,8 @@ def _generate_source_dir(self, source_dir: Optional[str]) -> str:
         :return: a path to the source directory of the archive directory
         """
         if not source_dir:
-            git.Repo.clone_from(
-                "https://github.com/TheRenegadeCoder/sample-programs.git", self._temp_dir.name)
+            logger.info(f"Source directory is not provided. Cloning the Sample Programs repo to a temporary directory: {self._temp_dir.name}.")
+            git.Repo.clone_from("https://github.com/TheRenegadeCoder/sample-programs.git", self._temp_dir.name)
             return os.path.join(self._temp_dir.name, "archive")
+        logger.info(f"Source directory provided: {self._source_dir}")
         return source_dir

tests/test_integration.py

@@ -3,48 +3,52 @@
 
 TEST_REPO = subete.load()
 
+
 def test_doc_url_multiword_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["Google Apps Script"]
+    language: LanguageCollection = TEST_REPO["Google Apps Script"]
     assert language.lang_docs_url() == "https://sample-programs.therenegadecoder.com/languages/google-apps-script"
 
+
 def test_doc_url_symbol_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["C#"]
+    language: LanguageCollection = TEST_REPO["C#"]
     assert language.lang_docs_url() == "https://sample-programs.therenegadecoder.com/languages/c-sharp"
 
+
 def test_testinfo_url_multiword_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["Google Apps Script"]
+    language: LanguageCollection = TEST_REPO["Google Apps Script"]
     assert language.testinfo_url() == "https://github.com/TheRenegadeCoder/sample-programs/blob/main/archive/g/google-apps-script/testinfo.yml"
 
+
 def test_testinfo_url_symbol_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["C#"]
+    language: LanguageCollection = TEST_REPO["C#"]
     assert language.testinfo_url() == "https://github.com/TheRenegadeCoder/sample-programs/blob/main/archive/c/c-sharp/testinfo.yml"
 
+
 def test_requirements_url_multiword_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["Google Apps Script"]
-    program: SampleProgram = language.sample_programs()["Hello World"]
+    program: SampleProgram = TEST_REPO["Google Apps Script"]["Hello World"]
     assert program.requirements_url() == "https://sample-programs.therenegadecoder.com/projects/hello-world"
 
+
 def test_requirements_url_symbol_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["C#"]
-    program: SampleProgram = language.sample_programs()["Hello World"]
+    program: SampleProgram = TEST_REPO["C#"]["Hello World"]
     assert program.requirements_url() == "https://sample-programs.therenegadecoder.com/projects/hello-world"
 
+
 def test_documentation_url_multiword_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["Google Apps Script"]
-    program: SampleProgram = language.sample_programs()["Hello World"]
+    program: SampleProgram = TEST_REPO["Google Apps Script"]["Hello World"]
     assert program.documentation_url() == "https://sample-programs.therenegadecoder.com/projects/hello-world/google-apps-script"
 
-def test_documentation_url_multiword_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["C#"]
-    program: SampleProgram = language.sample_programs()["Hello World"]
+
+def test_documentation_url_symbol_lang():
+    program: SampleProgram = TEST_REPO["C#"]["Hello World"]
     assert program.documentation_url() == "https://sample-programs.therenegadecoder.com/projects/hello-world/c-sharp"
 
+
 def test_article_issue_url_multiword_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["Google Apps Script"]
-    program: SampleProgram = language.sample_programs()["Hello World"]
+    program: SampleProgram = TEST_REPO["Google Apps Script"]["Hello World"]
     assert program.article_issue_query_url() == "https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+hello+world+google+apps+script"
 
+
 def test_article_issue_url_symbol_lang():
-    language: LanguageCollection = TEST_REPO.language_collections()["C#"]
-    program: SampleProgram = language.sample_programs()["Hello World"]
+    program: SampleProgram = TEST_REPO["C#"]["Hello World"]
     assert program.article_issue_query_url() == "https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+hello+world+c#"