Changeset - 323521344ae5
Parent rev.
Child rev.
[Not reviewed]
0 1 0
Brett Smith - 3 years ago 2021-04-29 15:35:47
brettcsmith@brettcsmith.org
books: Add docstrings throughout.
1 file changed with 59 insertions and 1 deletions:
conservancy_beancount/books.py
59
1
0 comments (0 inline, 0 general)
conservancy_beancount/books.py
➞
Show inline comments
 
"""books - Tools for loading the books"""
 
"""books - Tools for loading the books
 

			




	
	
	
		
 
This module provides common functionality for loading books split by fiscal


			




	
	
	
		
 
year and doing common operations on the results.


			




	
	
	
		
 
"""


			




	
	
	
		
 
# Copyright © 2020  Brett Smith


			




	...
	
		
 
@@ -41,2 +45,13 @@ Year = Union[int, datetime.date]


			




	
	
	
		
 
class FiscalYear(NamedTuple):


			




	
	
	
		
 
    """Convert to and from fiscal years and calendar dates


			




	
	
	
		
 

			




	
	
	
		
 
    Given a month and date that a fiscal year starts, this class provides


			




	
	
	
		
 
    methods to calculate the fiscal year of a given calendar date; to return


			




	
	
	
		
 
    important calendar dates associated with the fiscal year; and iterate


			




	
	
	
		
 
    fiscal years.


			




	
	
	
		
 

			




	
	
	
		
 
    Most methods can accept either an int, representing a fiscal year;


			




	
	
	
		
 
    or a date. When you pass a date, the method will calculate that date's


			




	
	
	
		
 
    corresponding fiscal year, and use it as the argument.


			




	
	
	
		
 
    """


			




	
	
	
		
 
    month: int = 3


			




	...
	
		
 
@@ -45,2 +60,6 @@ class FiscalYear(NamedTuple):


			




	
	
	
		
 
    def for_date(self, date: Optional[datetime.date]=None) -> int:


			




	
	
	
		
 
        """Return the fiscal year of a given calendar date


			




	
	
	
		
 

			




	
	
	
		
 
        The default date is today's date.


			




	
	
	
		
 
        """


			




	
	
	
		
 
        if date is None:


			




	...
	
		
 
@@ -53,2 +72,3 @@ class FiscalYear(NamedTuple):


			




	
	
	
		
 
    def first_date(self, year: Year) -> datetime.date:


			




	
	
	
		
 
        """Return the first calendar date of a fiscal year"""


			




	
	
	
		
 
        if isinstance(year, datetime.date):


			




	...
	
		
 
@@ -58,2 +78,3 @@ class FiscalYear(NamedTuple):


			




	
	
	
		
 
    def last_date(self, year: Year) -> datetime.date:


			




	
	
	
		
 
        """Return the last calendar date of a fiscal year"""


			




	
	
	
		
 
        return self.next_fy_date(year) - datetime.timedelta(days=1)


			




	...
	
		
 
@@ -61,2 +82,3 @@ class FiscalYear(NamedTuple):


			




	
	
	
		
 
    def next_fy_date(self, year: Year) -> datetime.date:


			




	
	
	
		
 
        """Return the last calendar date of a fiscal year"""


			




	
	
	
		
 
        if isinstance(year, datetime.date):


			




	...
	
		
 
@@ -102,2 +124,8 @@ class FiscalYear(NamedTuple):


			




	
	
	
		
 
class LoadResult(NamedTuple):


			




	
	
	
		
 
    """Common functionality for loaded books


			




	
	
	
		
 

			




	
	
	
		
 
    This class is type-compatible with the return value of the loader


			




	
	
	
		
 
    functions in ``beancount.loader``. This provides named access to the


			




	
	
	
		
 
    results, as well as common functionality methods.


			




	
	
	
		
 
    """


			




	
	
	
		
 
    entries: Entries


			




	...
	
		
 
@@ -108,2 +136,9 @@ class LoadResult(NamedTuple):


			




	
	
	
		
 
    def empty(cls, error: Optional[Error]=None) -> 'LoadResult':


			




	
	
	
		
 
        """Create a return result that represents nothing loaded


			




	
	
	
		
 

			




	
	
	
		
 
        If an error is provided, it will be the sole error reported.


			




	
	
	
		
 

			




	
	
	
		
 
        This method is useful to create a LoadResult when one can't be


			




	
	
	
		
 
        created normally; e.g., because a books path is not properly configured.


			




	
	
	
		
 
        """


			




	
	
	
		
 
        errors: Errors = []


			




	...
	
		
 
@@ -118,2 +153,10 @@ class LoadResult(NamedTuple):


			




	
	
	
		
 
    ) -> Iterator[data.Posting]:


			




	
	
	
		
 
        """Iterate all the postings in this LoadResult


			




	
	
	
		
 

			




	
	
	
		
 
        If ``rewrites`` are provided, postings will be passed through them all.


			




	
	
	
		
 
        See the ``reports.rewrite`` pydoc for details.


			




	
	
	
		
 

			




	
	
	
		
 
        If ``search_terms`` are provided, postings will be filtered through


			




	
	
	
		
 
        them all. See the ``cliutil.SearchTerm`` pydoc for details.


			




	
	
	
		
 
        """


			




	
	
	
		
 
        postings = data.Posting.from_entries(self.entries)


			




	...
	
		
 
@@ -128,2 +171,3 @@ class LoadResult(NamedTuple):


			




	
	
	
		
 
    def load_account_metadata(self) -> None:


			




	
	
	
		
 
        """Load account metadata from this LoadResult"""


			




	
	
	
		
 
        return data.Account.load_from_books(self.entries, self.options_map)


			




	...
	
		
 
@@ -131,2 +175,6 @@ class LoadResult(NamedTuple):


			




	
	
	
		
 
    def print_errors(self, out_file: TextIO) -> bool:


			




	
	
	
		
 
        """Report errors from this LoadResult to ``out_file``


			




	
	
	
		
 

			




	
	
	
		
 
        Returns True if errors were reported, False otherwise.


			




	
	
	
		
 
        """


			




	
	
	
		
 
        for error in self.errors:


			




	...
	
		
 
@@ -141,2 +189,7 @@ class LoadResult(NamedTuple):


			




	
	
	
		
 
    def returncode(self) -> int:


			




	
	
	
		
 
        """Return an appropriate Unix exit code for this LoadResult


			




	
	
	
		
 

			




	
	
	
		
 
        If this LoadResult has errors, or no entries, return an exit code that


			




	
	
	
		
 
        best represents that. Otherwise, return the standard OK exit code 0.


			




	
	
	
		
 
        """


			




	
	
	
		
 
        if self.errors:


			




	...
	
		
 
@@ -267,2 +320,7 @@ class Loader:


			




	
	
	
		
 
    ) -> LoadResult:


			




	
	
	
		
 
        """High-level, "do-what-I-mean"-ish books loader


			




	
	
	
		
 

			




	
	
	
		
 
        Most tools can call this with a books loader from configuration, plus


			




	
	
	
		
 
        one or two fiscal year arguments, to get the LoadResult they want.


			




	
	
	
		
 
        """


			




	
	
	
		
 
        if loader is None:


			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







    


    

  


    








    
        Server instance: kapok.sfconservancy.org-28352
    
    
        This site is powered by
            Kallithea 0.6.3,
        which is
        © 2010–2020 by various authors & licensed under GPLv3.
            – Support
        – Privacy Policy