Restructure project to have supporting files inside a "dfiq" director…

…y. Replace os.path usages with pathlib.Path. Other minor refactoring.

dfiq/__init__.py

@@ -0,0 +1,5 @@
+from .dfiq import DFIQ, Scenario, Facet, Question, Approach
+__all__ = ['DFIQ', 'Scenario', 'Facet', 'Question', 'Approach']
+__version__ = '1.0.0'
+__author__ = 'Ryan Benson'
+__email__ = '[email protected]'

dfiq.py → dfiq/dfiq.py

@@ -12,13 +12,16 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import importlib.resources
 import jinja2
 import logging
 import networkx as nx
 import os
 import re
 import yamale
 import yaml
+from pathlib import Path
+
 
 logging.basicConfig(
  level=logging.DEBUG, format="%(filename)s | %(levelname)s | %(message)s"
@@ -71,9 +74,8 @@ def __init__(
  if not self.parent_ids:
  self.parent_ids = set()
 
- if description:
- if isinstance(description, str):
- self.description = description.rstrip()
+ if isinstance(description, str):
+ self.description = description.rstrip()
 
  if self.id[1] == "0":
  self.is_internal = True
@@ -202,8 +204,8 @@ class DFIQ:
  relationships.
 
  Attributes:
- yaml_data_path (str): The path to the directory containing the DFIQ YAML files.
- markdown_output_path (str, optional): The path to the directory where the
+ yaml_data_path (Path): The path to the directory containing the DFIQ YAML files.
+ markdown_output_path (Path, optional): The path to the directory where the
  generated Markdown files should be saved.
  plural_map (dict): A dictionary mapping from DFIQ component types to their
  plural forms.
@@ -217,9 +219,9 @@ class DFIQ:
 
  def __init__(
  self,
- yaml_data_path: str = "data",
- markdown_output_path: str | None = None,
- templates_path: str = "templates",
+ yaml_data_path: Path = Path("../../data"),
+ markdown_output_path: Path | None = None,
+ templates_path: Path = Path("../templates"),
  ) -> None:
  self.yaml_data_path = yaml_data_path
  self.markdown_output_path = markdown_output_path
@@ -362,7 +364,7 @@ def load_yaml_files_by_type(
  ) -> dict:
  """Load all DFIQ YAML files of a given type from the appropriate path.
 
- Given the yaml_data_path, locate the correct sub-directory for that
+ Given the yaml_data_path, locate the correct subdirectory for that
  dfiq_type, validate any YAML files there, and load them into a dict.
 
  Args:
@@ -410,12 +412,24 @@ def validate_yaml_file(yaml_file_path: str) -> bool:
  return False
  return True
 
+ @staticmethod
+ def _get_dfiq_file(subdirectory, file_name=None):
+ """Load a data file bundled in the dfiq package. If multiple subdirectories are needed, use . to separate them."""
+ if file_name:
+ return importlib.resources.files(f'dfiq.{subdirectory}').joinpath(file_name)
+ else:
+ return importlib.resources.files(f'dfiq.{subdirectory}')
+
+ def _get_dfiq_directory(self, subdirectory):
+ return importlib.resources.as_file(self._get_dfiq_file(subdirectory))
+
  def _load_dfiq_schema(self) -> None:
  """Load Yamale 'spec' files to use for validation."""
- self.schemas["Scenario"] = yamale.make_schema("utils/scenario_spec.yaml")
- self.schemas["Facet"] = yamale.make_schema("utils/facet_spec.yaml")
- self.schemas["Question"] = yamale.make_schema("utils/question_spec.yaml")
- self.schemas["Approach"] = yamale.make_schema("utils/approach_spec.yaml")
+
+ self.schemas["Scenario"] = yamale.make_schema(self._get_dfiq_file('utils', 'scenario_spec.yaml'))
+ self.schemas["Facet"] = yamale.make_schema(self._get_dfiq_file('utils', 'facet_spec.yaml'))
+ self.schemas["Question"] = yamale.make_schema(self._get_dfiq_file('utils', 'question_spec.yaml'))
+ self.schemas["Approach"] = yamale.make_schema(self._get_dfiq_file('utils', 'approach_spec.yaml'))
 
  def validate_dfiq_schema(self, yaml_file_path: str, component_type: str) -> bool:
  """Validate that a YAML file adheres to the appropriate DFIQ Schema."""
@@ -470,7 +484,7 @@ def generate_scenario_md(
  scenario = self.components.get(scenario_id)
 
  if not scenario:
- raise Exception(f"Unable to find {scenario_id} in components dictionary")
+ raise ValueError(f"Unable to find {scenario_id} in components dictionary")
 
  if scenario.is_internal and not allow_internal:
  logging.warning(
@@ -484,12 +498,12 @@ def generate_scenario_md(
  "components": self.components,
  "allow_internal": allow_internal,
  }
+
  content = template.render(context)
- with open(
- os.path.join(self.markdown_output_path, "scenarios", f"{scenario_id}.md"),
- mode="w",
- ) as file:
- file.write(content)
+ output_path = Path(self.markdown_output_path, "scenarios", f"{scenario_id}.md")
+ output_file = Path(output_path)
+ output_file.parent.mkdir(exist_ok=True, parents=True)
+ output_file.write_text(content, encoding='utf-8')
 
  def generate_question_md(
  self,
@@ -511,7 +525,7 @@ def generate_question_md(
  question = self.components.get(question_id)
 
  if not question:
- raise Exception(f"Unable to find {question_id} in components dictionary")
+ raise ValueError(f"Unable to find {question_id} in components dictionary")
 
  if question.is_internal and not allow_internal:
  logging.warning(
@@ -531,15 +545,18 @@ def generate_question_md(
  "components": self.components,
  "allow_internal": allow_internal,
  }
- content = template.render(context)
- output_path = os.path.join(
- self.markdown_output_path, "questions", f"{question_id}.md"
- )
- with open(output_path, mode="w") as file:
- file.write(content)
 
+ content = template.render(context)
+ output_path = Path(self.markdown_output_path, "questions", f"{question_id}.md")
+ self.write_content_to_file(content, output_path)
  logging.info(f"Wrote Markdown for Question {question_id} to {output_path}")
 
+ @staticmethod
+ def write_content_to_file(content: str, file_path: Path) -> None:
+ output_file = Path(file_path)
+ output_file.parent.mkdir(exist_ok=True, parents=True)
+ output_file.write_text(content, encoding='utf-8')
+
  def generate_question_index_md(self, allow_internal: bool = False) -> None:
  """Generates Markdown for the index page listing all Questions.
 
@@ -553,10 +570,9 @@ def generate_question_index_md(self, allow_internal: bool = False) -> None:
  template = self.jinja_env.get_template("questions_index.jinja2")
  context = {"components": self.components, "allow_internal": allow_internal}
  content = template.render(context)
- with open(
- os.path.join(self.markdown_output_path, "questions", "index.md"), mode="w"
- ) as file:
- file.write(content)
+ output_path = Path(self.markdown_output_path, "questions", "index.md")
+ self.write_content_to_file(content, output_path)
+ logging.info(f"Wrote Markdown for Question Index to {output_path}")
 
  def generate_approach_glossary_md(self, allow_internal: bool = False) -> None:
  """Generates Markdown for the Approach Glossary page, listing common items in Approaches.
@@ -617,10 +633,5 @@ def generate_approach_glossary_md(self, allow_internal: bool = False) -> None:
  "components": self.components,
  }
  content = template.render(context)
- with open(
- os.path.join(
- self.markdown_output_path, "contributing", "approach_glossary.md"
- ),
- mode="w",
- ) as file:
- file.write(content)
+ output_path = Path(self.markdown_output_path, "contributing", "approach_glossary.md")
+ self.write_content_to_file(content, output_path)