Changeset - bf09cebf7352
[Not reviewed]
0 1 0
Brett Smith - 3 years ago 2021-03-09 21:32:41
brettcsmith@brettcsmith.org
query: Add overview docstring.
1 file changed with 41 insertions and 1 deletions:
0 comments (0 inline, 0 general)
conservancy_beancount/reports/query.py
Show inline comments
 
"""query.py - Report arbitrary queries with advanced loading and formatting"""
 
"""query.py - Report arbitrary queries with advanced loading and formatting
 

	
 
This tool extends Beancount's bean-query with the following:
 

	
 
* ``META_DOCS("meta-key")`` function: Given the name of metadata with
 
  documentation in it, returns a list of the documentation links.
 

	
 
* ``STR_META("meta-key")`` function: Looks up metadata like ANY_META, then
 
  returns the result as a nicely formatted string, to make sorting easier or
 
  just provide prettier reports.
 

	
 
* ``SET()`` function: Returns only unique arguments over a GROUP BY.
 

	
 
* ODS output format, with proper formatting of currency and documentation links.
 

	
 
* Loads books from your configuration file, with options available to specify
 
  which year(s) to load.
 

	
 
* Can load rewrite rules just like other reports. Your queries will show the
 
  transformed entries.
 

	
 
* Improved error reporting.
 

	
 
Run it like bean-query, except instead of specifying a books filename, use
 
date options like ``--begin``, ``--end``, ``--fy``, and ``--cy`` to specify
 
the year(s) you want to load. Run ``query-report --help`` for details about
 
those.
 

	
 
Start an interactive shell::
 

	
 
    query-report [year options]
 

	
 
Write a spreadsheet with results for one query::
 

	
 
    query-report [year options] [-O OUTPUT.ods] <query string>
 

	
 
    query-report [year options] [-O OUTPUT.ods] < QUERY_FILE.bql
 

	
 
query-report also accepts all the same options as bean-query, like ``--format``
 
and ``--numberify``.
 
"""
 
# Copyright © 2021  Brett Smith
 
# License: AGPLv3-or-later WITH Beancount-Plugin-Additional-Permission-1.0
 
#
 
# Full copyright and licensing details can be found at toplevel file
 
# LICENSE.txt in the repository.
 

	
 
import argparse
 
import contextlib
 
import datetime
 
import enum
 
import functools
 
import itertools
 
import logging
 
import sys
 

	
 
from typing import (
 
    cast,
 
    Any,
 
    Callable,
 
    Dict,
 
    Iterable,
 
    Iterator,
 
    List,
 
    Mapping,
 
    NamedTuple,
 
    Optional,
 
    Sequence,
 
    TextIO,
 
    Tuple,
 
    Type,
 
    Union,
 
)
 
from ..beancount_types import (
 
    MetaKey,
 
    MetaValue,
 
)
 

	
 
from decimal import Decimal
 
from pathlib import Path
 
from beancount.core.amount import _Amount as BeancountAmount
 
from beancount.core.inventory import Inventory
 
from beancount.core.position import _Position as Position
 

	
 
import beancount.query.numberify as bc_query_numberify
 
import beancount.query.query_compile as bc_query_compile
 
import beancount.query.query_env as bc_query_env
 
import beancount.query.query_execute as bc_query_execute
 
import beancount.query.query_parser as bc_query_parser
 
import beancount.query.query_render as bc_query_render
 
import beancount.query.shell as bc_query_shell
 
import odf.table  # type:ignore[import]
 

	
 
from . import core
 
from . import rewrite
 
from .. import books
 
from .. import cliutil
 
from .. import config as configmod
 
from .. import data
 
from .. import rtutil
 

	
 
PROGNAME = 'query-report'
 
logger = logging.getLogger('conservancy_beancount.reports.query')
 

	
 
CellFunc = Callable[[Any], odf.table.TableCell]
 
EnvironmentFunctions = Dict[
 
    # The real key type is something like:
 
    #   Union[str, Tuple[str, Type, ...]]
 
    # but two issues with that. One, you can't use Ellipses in a Tuple like
 
    # that, so there's no short way to declare this. Second, Beancount doesn't
 
    # declare it anyway, and mypy infers it as Sequence[object]. So just use
 
    # that.
 
    Sequence[object],
 
    Type[bc_query_compile.EvalFunction],
 
]
 
RowTypes = Sequence[Tuple[str, Type]]
 
Rows = Sequence[NamedTuple]
 
Store = List[Any]
 
QueryExpression = Union[
 
    bc_query_parser.Column,
 
    bc_query_parser.Constant,
 
    bc_query_parser.Function,
 
    bc_query_parser.UnaryOp,
 
]
 
QueryStatement = Union[
 
    bc_query_parser.Balances,
 
    bc_query_parser.Journal,
 
    bc_query_parser.Select,
 
]
 

	
 
# This class supports type checking. Beancount code dynamically sets the
 
# ``store`` attribute, in bc_query_execute.execute_query().
 
class Context(bc_query_execute.RowContext):
 
    store: Store
 

	
 

	
 
class MetaDocs(bc_query_env.AnyMeta):
0 comments (0 inline, 0 general)