• var descriptions from cfg.py
• add sections
• check all variables from spec have decriptions
• generate frontend README.d with sparllines using mako templates
• rename current root README to DEV.md
• add github.io version

As of now in documentation I have an issue with modules.rst file. In runtime I get an error message:

\mini-kep\doc\rst\modules.rst:: WARNING: document isn't included in any toctree

I'm not understanding why modules.rst needed at all? It this a default file to insert to index.rst?

@aptiko, are you familiar with this? @dz0 ?

Imports and usage from src/config.py file

1. config.py DataFolder used in:

• src/word2csv/word.py

def make_interim_csv(year, month):
    from config import DataFolder
    folder = DataFolder(year, month).get_raw_folder()
    interim_csv = DataFolder(year, month).get_interim_csv()
    folder_to_csv(folder, interim_csv)
    return True

2. config.py DateHelper used in:

• src/finaliser.py

from config import PathHelper, DateHelper

...

def copy_latest():
    year, month = DateHelper.get_latest_date()
    print(f'Latest date is {year} {month}.')
    src_folder = PathHelper.get_processed_folder(year, month)

• src/csv2df/parser.py (under if __main__):

    from config import PathHelper, DateHelper
    ...
    year, month = DateHelper.get_latest_date()
    csv_path = PathHelper.locate_csv(year, month)

• src/csv2df/reader.py (under if __main__):

    from config import PathHelper, DateHelper
    ...
    year, month = DateHelper.get_latest_date()
    csv_path = PathHelper.locate_csv(year, month)

• src/csv2df/runner.py

from config import DateHelper, PathHelper

...

class Collection:
    """Methods to manipulate entire set of data releases."""

    all_dates = DateHelper.get_supported_dates()

    @staticmethod
    def save_latest():
        year, month = DateHelper.get_latest_date()
        latest_vintage = Vintage(year, month)
        latest_vintage.save()

    @staticmethod
    def approve_latest():
        """Quick check for algorithm on latest available data."""
        year, month = DateHelper.get_latest_date()
        latest_vintage = Vintage(year, month)
        latest_vintage.validate()

3. config.py PathHelper used in:

• src/finaliser.py

from config import PathHelper, DateHelper

...

def copy_latest():
    year, month = DateHelper.get_latest_date()
    print(f'Latest date is {year} {month}.')
    src_folder = PathHelper.get_processed_folder(year, month)
    dst_folder = PathHelper.get_latest_folder()
    copied = []
    for src in [f for f in src_folder.iterdir() if f.is_file()]:
        dst = dst_folder / src.name
        shutil.copyfile(src, dst)
        copied.append(src)
        print('Copied', src)
    print(f'Updated folder {dst_folder}')
return copied

...

def save_xls():
    ...
    filepath = PathHelper.get_xl_path()
    to_xls(filepath, dfa, dfq, dfm)
    print('Saved', filepath)

• src/getter.py

from config import PathHelper

...

def get_dataframe(freq):
    path = PathHelper.get_latest_csv(freq)
    content = Path(path).read_text()
   ...

• src/csv2df/parser.py (under if __main__):

    from config import PathHelper, DateHelper
    ...
    year, month = DateHelper.get_latest_date()
    csv_path = PathHelper.locate_csv(year, month)
    csvfile = reader.open_csv(csv_path)

• src/csv2df/reader.py (under if __main__):

    from config import PathHelper, DateHelper
    ...
    year, month = DateHelper.get_latest_date()
    csv_path = PathHelper.locate_csv(year, month)
    csvfile = open_csv(csv_path)

• src/csv2df/runner.py (mentioned in module docstring):

from config import DateHelper, PathHelper

...

class Vintage:
    """Represents dataset release for a given year and month."""

    def __init__(self, year, month):
        self.year, self.month = year, month
        csv_path = PathHelper.locate_csv(year, month)
        with open_csv(csv_path) as csvfile:
            self.dfa, self.dfq, self.dfm = get_dataframes(csvfile)

    def dfs(self):
        """Shorthand for obtaining three dataframes."""
        return self.dfa, self.dfq, self.dfm

    def save(self):
        folder_path = PathHelper.get_processed_folder(self.year, self.month)
        self.dfa.to_csv(folder_path / 'dfa.csv')
        self.dfq.to_csv(folder_path / 'dfq.csv')
        self.dfm.to_csv(folder_path / 'dfm.csv')
        print("Saved dataframes to", folder_path)
        return True

• src/csv2df/tests/test_various_bugs.py

from config import PathHelper

...

def test_csv_has_no_null_byte():
    csv_path = PathHelper.locate_csv(2015, 2)
    z = csv_path.read_text(encoding='utf-8')
    assert "\0" not in z

• src/download/download.py

from config import PathHelper

UNPACK_RAR_EXE = PathHelper.get_unrar_binary()

...

def unrar(path, folder, unrar=UNPACK_RAR_EXE):
    ...
class RemoteFile():

    def __init__(self, year, month):
        self.year, self.month = year, month
        ...
        folder = PathHelper.get_raw_folder(year, month)
        self.folder = str(folder)
        self.local_path = str(folder / 'ind.rar')
    ...

2. в классе DataRows плохо то что данные инициализируются не в конструкторе (хотя бы дефолтные), а только при вызове parse_row: self.a, self.m, self.q.
   Аналолично у класса Table (self.a, self.q, self.m)

3. Не нравится класс DataRows как таковой. Вся его работа вырождается в 1 ф-цию, label и splitter_func у которой доступны внешне у вызываемого кода (из класса Table).
   Я бы перенес его логику (ф-цию parse_row из DataRows) в вызываемую сторону, в сам класс Table, а класс DataRows удалил:
   def parse_row(self, year, values)
   в которой, очевидно, автоматически уже будут доступны self.label и self.splitter_func, плюс здесь можно будет сразу работать c результатами парсинга:

self.a.append(ds.a)
self.q.extend(ds.q)
self.m.extend(ds.m)

11. Несколько непрозрачная работа классa Table, сейчас получается что работа с ним должна быть грубо говоря такой:
    а) создали б) вызвали parse, в нём в частности проставилась splitter_func'ция, плюс еще доп. телодвижения с хидером, далее
    при вызове метода calc идет работа в частности с настроенной self.splitter_func.
    Иными словами, если не знать эту последовательность действий для работы с Table, вызов её calc упадет где-то так:
    AttributeError: 'Table' object has no attribute 'splitter_func'.

В свою очередь класс Datapoints полагается на то, что ему при создании передаются "уже настроенные таблицы",
в которых эта splitter_func была проставлена, и спокойно вызывает табличный метод calc.

Не многовато ли допущений, вопрос? Можно попробовать хотя бы сокрыть внешне все эти сложности,
перенеся ф-цию get_all_tables непосредственно в класс Datapoints, где Datapoints уже в конструкторе
сделает все необходимые "донастройки" таблиц и об этом внешне не надо будет беспокоиться.

Must show sequence of parsing commands for easier understanding of algorithm

• download latest rar
• unpack rar
• supply directory to word.py
• run word.py
• copy tab.csv to interim folder
• change contants for latest year, month
• make new folder for latest in processed
• run save latest
• copy to latest folder in files.py
• generate new frontpage
• copy frontpage code
• save this directions

... from https://github.com/epogrebnyak/data-rosstat-kep

run files:

• cfg.py
• vint.py
• other?

cell.filter_value() был сделан исторически по принципу валится-чиним. чтобы его улучшить нужен поток всех значений из даже неотпарсенных таблиц. Это даст занчения типа "93,3,", которые сейчас не ловятся.

file: mini-kep/src/frontpage/_latest.md
displays broken characters:

В классе Frame есть методы get_dfa, get_dfq, get_dfm.

Выродилось из комментария в коде:

TO DISCUSS: get_df*() creates data every time we call them,
may create self.dfa, etc and return.

Предлагается создавать по требованию 1 раз, далее возвращать уже созданный инстанс.

Речь про метод vaildate в классе Дефиниции и Спецификации.
Открытые вопросы на обсуждение:

Как предполагается использовать методы validate в Спецификации и Дефиниции?

Как реагировать на невалидные данные: игнорировать и выбрасывать варнинг, падать, или еще каким-то образом?

Может быть вынести эту логическую часть во внешнюю сторону, т.к. сейчас опять придем примерно к той же ситуации, что была с классом Table (где объекты могут иметь невалидное состояние).

Можно завести т.н. Валидаторы, в которых реализовать всю эту логику, как для Спецификаций, так и для Дефиниций.

Плюс завернуть получение Спецификации и Дефиниций сразу в этот валидатор, который на выходе даст только валидные объекты и отрапортует о найденных проблемах.

Это на уровне идеи.

csv2df.helpers.DATES should be replaced with a get_supported_dates(), which:

• starts at DATES[0]
• continious to current year, month
• excludes one date excluded in DATES
• very, very loosely follows this schedule, eg in any date in August we consider July an allowed date.

Need a test for this and code for get_supported_dates() on a separate branch

Will put a user case here for the API, to work on a solution. Sorry this takes long to describe.

1. в методе pop_segment необязательно работать с копией csv_dicts, можно напрямую с self.csv_dicts

    def pop_segment(self, start, end):
        """Pops elements of self.csv_dicts between [start, end). 
           Recognises element occurences by index *i*."""           
        #remaining_csv_dicts = self.csv_dicts.copy()
        we_are_in_segment = False
        segment = []
        i = 0
        while i < len(self.csv_dicts):
            row = self.csv_dicts[i]
            line = row['head']
            if is_matched(start, line):
                we_are_in_segment = True
            if is_matched(end, line):
                break
            if we_are_in_segment:
                segment.append(row)
                del self.csv_dicts[i]
            else:    
                # else is very important, wrong indexing without it
                i += 1
        #self.csv_dicts = remaining_csv_dicts
        return segment -->

4. в методе calc получение года (через get_year) нужно только если прошло условие len(row['data'])>0,
   можно перенести его туда ниже.

5. Здесь же, в методе calc вместо:
   if len(row['data'])>0:
   можно идиоматически:
   if row['data']:

8. В классе Table я бы поменял нейминг полей:
   вместо

self.textrows = textrows
self.datarows = datarows

сделал

self.headers = headers
self.datarows = datarows

тем более что и инстанциируется этот класс как раз с headers и datarows:

yield Table(headers, datarows)

Как по мне, так будет понятнее.

9. в методе fix_multitable_units

def fix_multitable_units(blocks):
    """For those blocks which do not have parameter definition,
       but do not have any unknown rows, copy parameter 
       from previous block
    """
    for prev_block, block in zip(blocks, blocks[1:]):
        if block.header.unknown_lines() == 0 and \
           block.header.varname is None:
           block.header.varname = prev_block.header.varname

лучше поменять местами условия в ветке if, т.к проверка на is None гораздо быстрее чем проверка на unknown_lines(),
в которой делается вагон и маленькая тележка действий; т.е предлагаю сделать так:
if block.header.varname is None and block.header.unknown_lines() == 0:

12. может быть я что-то упустил, но разве в ф-ции get_all_tables нужна последняя строка:
    return [t for t in all_tables if t.label and t.label not in exclude]
    ?
    Можно сразу возвращать all_tables, они уже отфильтрованы, потому что в текущей реализации здесь
    фильтрация делается на каждой итерации ""for pdef in spec[1:]:"", где вызывается get_tables, в которой эта фильтрация и происходит.
    т.о. к концу выполнения ф-ции get_all_tables, список all_tables хранит готовые отфильтрованные данные, и последняя строчка
    return [t for t in all_tables if t.label and t.label not in exclude] избыточна.

This review is similar to #38.

The algorithm may break if markers (start and end lines) are not in order, to check for that:
- must read csv file rows, use a reference csv file (use files.get_latest())
- use first pair in start and end markers
- make sure the order of markers in specification is the same order as in csv file

Need addition to test_cfg.py or validation method in cfg.spec:

Предлагаю перенести все проверки из модуля cfg ко всем остальным проверкам модуля cfg, в файл test_cfg.py, если нет возражений.
Аналогично для модуля tables, перенести в test_tables.py.

1. В текущей версии класса Table проперти npoints некорректное (стало после изменений в классе в последние дни).
   Сейчас оно используется в def repr(self) разве что. Недочет в том, что класс не содержит self.a, self.q, self.m (переехали в Emitter),
   т.о. всегда будет ловиться эксепшн AtributeError: 'Table' object has no attribute 'a' и возвращаться 0 (см. реализацию npoints).
   Предлагаю удалить проперти npoints и удалить работу с ним в repr

2. Подобная проблема здесь же, в методе str, не определён self.textrows у класса Table:
   msg = "\nTable with {} header(s) and {} datarow(s)".format(len(self.textrows),
   self.nrows)
   будет эксепшн

Some refactoring proposals given at: https://github.com/sdgupta/mini-kep/blob/master/src/kep/parse_refactored.py

Todo @sd:

• mark comment with initials and start comment on new line before commented code

TODO:

• dir structure
• list of notebooks
• frontend.md
• code review parse.py
• transform GOV_EXPENSE_ACCUM, GOV_REVENUE_ACCUM, GOV_SURPLUS_ACCUM
• interface to processed data
• generate excel wtih variable names

Tasks

List of notebooks

Make notebook README.MD:

• vintages / revisions (make markdown based on MS Word)
• datalab
• inflation components
• bank reserves vs oil
• variations in variables
• macro assumptions for stress testing

OUT OF SCOPE

• read SEP + update KEP with SEP data
• prior to 1999

Datadriven comment

• Using incomplete dir structure
• DAG for economist

    # REQUIREMENT: 
    # pick new vars by requirement for features   
    # var desciptions by section with latest data
    # detrended data
    # revisions analysis
    # dataset organisation - what we want:
        # latest dataset
        # variable by vintages
        # seasonally adjusted series
        
        
    
    # TODO-PARSING:         
    # convert more existing parsing definitions to cfg.py    
    # add more control datapoints        
    
    #FIXME: generate Excel files and plots
    #def to_excel(dfs, filename):
    #    dfa, dfq, dfm = dfs
    #    with pd.ExcelWriter(filename) as writer:
    #        dfa.to_excel(writer, sheet_name='year')
    #        dfq.to_excel(writer, sheet_name='quarter')
    #        dfm.to_excel(writer, sheet_name='month')
    #        #FIXME - write variable names to sheet, by section 
    #
    ##for file in [config.XLSX_FILE, config.XLS_FILE]:
    ##   to_excel(file)

There is a dependency and runtime graph for calling csv2df.runner.Vintage(2017, 5) by @dz0 gerenrated with pycallgraph.

The graph is here ('Open in new tab' will enlarge) and to me it was a lot to say:

• csv2df.parser is overloaded with logic: it both makes tables and parses them
• 8 call from runner to reader is 8 segments in defintion
• numers on the upper side of Emitter graph: "yes, we are making 3 data frames"
• lower part of Emitter graph: the numbers refer to number of variables and datapoints generated

Pycallgraph seems stalled itself, but I think we can use this chart as reference.

Речь про строки:

elif not s or not e:
    raise ValueError("Single None as a marker cannot be processed")

в методе pop класса RowStack.

в случаях:
1)
marker['start'] явл. пустой строкой, т.е ""
marker['end'] явл. строкой "abc"
2)
marker['end'] явл. пустой строкой, т.е ""
marker['start'] явл. строкой "abc"

получим мутное сообщение эксепшна, что якобы был задан 1 None, хотя это не так (пустая строка - это не None).

http://www.gks.ru/free_doc/new_site/vvp/kv/tab6.htm

2011:

GDP_2011_Q = [13255.3, 14345.3, 15615.1, 16482.4]

After done with refactoring:

• rename kep to csv2df
• rename modules in src/kep to reader-parser-emitter:
  • combine rows and splitter modules, make reader
  • rename tables to parser
  • make emitter

I made some sphinx documentation for files module:

• module source
• docs source
• docs html

7. В методе get_all_tables сейчас захардкожено то что мы полагаем что сперва идет дефолтная дефиниция, затем все extra.
   Если где-то это не будет выполняться (неверно заданы данные в cfg.py, забыли о таком правиле, итд), код поломается
   (но, возможно, это даже и хорошо, станет раньше заметно ошибку). Может стоит в cfg.py как-то это заложить: заведение дефолтной дефиниции и всех остальных extra,
   чтобы было наглядно и очевидно?

Current documentation:

http://mini-kep-parcer-for-rosstat-kep-publication.readthedocs.io/en/latest/

Doc folder:

https://github.com/epogrebnyak/mini-kep/tree/master/doc

Script to generate docs:

ctx.run("sphinx-apidoc -efM -o doc src\csv2df *test_*")
at tasks.py

My idea of the docs is the follwoing:

1. documentation page shows intro.rst and glossary.rst for the project
   and links to src/packages folders:

   • download
   • word2csv (will rename, it is now called word)
   • csv2df
   • frontpage

The link is a module name, possibly followed by a short comment. Can this comment be a module docstring?

2. At csv2df page I want a listing of modules with their docstrings. In listing I would prefer to control order of modules listed as:
   • helpers
   • specification
   • reader
   • parcer
   • runner
   • validator
   • util_label
   • util_row_splitter

Can this order be specified somewhere, eg __all__constant?

3. When clicking on module name like 'helpers' I get its documentation.

For this structure I need a new commnd to put at tasks.py + manual edit of some .rst files, apparently.

Extend variable definitions in spec.py using https://github.com/epogrebnyak/mini-kep/tree/master/reference/parsing_definitions

WARNING: unexpected row length 3
WARNING: unexpected row length 11
WARNING: unexpected row length 11

• на каких рядах они возникают?
• что с этим делать?

6. в ф-ции get_year регулярку можно использовать сразу готовую, предварительно скомпильнутую,
   как сделано к примеру с ""_COMMENT_CATCHER = re.compile("\D*([\d.,])\s(?=\d))")""

10. в cell.py есть ф-ция get_year, в parser.py есть ф-ция get_year, нужно определиться где ей находиться.

https://codecov.io/gh/epogrebnyak/mini-kep or coveralls
https://github.com/epogrebnyak/mini-kep/blob/master/.travis.yml#L11-L12

Need step-by-step procedure resulting in coverage badge in README.md.

Есть три варианта отрисовки данных :

1. https://github.com/epogrebnyak/mini-kep/blob/master/src/frontpage/VALUES.md - сплайны, код где-то в папке frontpage
   

2. https://github.com/epogrebnyak/data-rosstat-kep и код тут
   

3. https://github.com/epogrebnyak/data-lab (группы показателей)
   

Мне не нравится, что это три разные отрисовки, код в разных местах. Первая задача собрать код этих рисунков в одном месте.

Reading csv files and filtering csv rows not tested. May split some functions in order to test. See Ned's lecture.

Here is the code for module docstring:
https://github.com/epogrebnyak/mini-kep/blob/master/src/csv2df/helpers.py

and here how it looks like in documentation:
http://mini-kep-parcer-for-rosstat-kep-publication.readthedocs.io/en/latest/csv2df.html#module-csv2df.helpers

The problem: function names are in bold, but there no clickable links.

See list of todos in readme.

Files:

• html: http://mini-kep-docs.s3-website-eu-west-1.amazonaws.com/kep.spec.html
• code: https://github.com/epogrebnyak/mini-kep/blob/master/src/kep/spec.py
• test: https://github.com/epogrebnyak/mini-kep/blob/master/src/kep/tests/test_spec.py
• rst: https://github.com/epogrebnyak/mini-kep/blob/master/doc/kep.files.rst

• data/pocessed/latest - make utility that copies files to latest on update
• some code below for updating make_latest.py - see MAKE/docopt syntax for common tasks in repo if necessary

import cfg
import parse 

if __name__ == '__main__':    
    # check latest date data           
    parse.approve_latest()               
    
    # check all dates, runs slow (about 20 sec.) + may fail if dataset not complete      
    parse.approve_all()

    # save dataframes to csv 
    parse.save_all_dfs()
    
    # interim to processed data cycle: (year, month) -> 3 dataframes
    #use None, None for latest values
    year, month = 2017, 4 
    # source csv file
    csv_path = cfg.get_path_csv(year, month)  
    # break csv to tables with variable names
    tables = parse.get_all_valid_tables(csv_path)
    # emit values from tables
    dpoints = parse.Datapoints(tables)    
    # convert stream values to pandas dataframes     
    frame = parse.Frame(datapoints=dpoints)
    # save dataframes to csv files  
    processed_folder = cfg.get_processed_folder(year, month)    
    frame.save(processed_folder)       
    # end of cycle 
    
   # sample access - dataframes
    dfa = frame.get_dfa()
    dfq = frame.get_dfq()
    dfm = frame.get_dfm()     

Some cleanup / excercise based on 'dirty' test by @bakakaldsas here. Hope you don't mind me pulling this to issue, it should help coming to common testing style. It extends #24 in a way.

There are two things to 'clean' in test structure and several option on how to test.

Test structure:

• test naming should be observed, as with rest of python classes. Suggested name is Test_open_csv(). Caps for test name, lowercase due to it is testing a function open_csv. It should not be all lowercase for testclass.
• the part like below showld bertter go to either setup_method or a separate fixture. As we are not using it outside the class can settle for setup method.

    from pathlib import Path
    class MockPath(type(Path())):
        def open(self, mode='r', buffering=-1, encoding=None, errors=None, newline=None):
            return "test"

    path_good = MockPath()
    path_bad = "This is not pathlib.Path, this is a string"

As for the test essence there are several things we can test:

1. is open_csv() callable
2. can it open a file?
3. can it open a file and the contents of the file is right?

(3) is a bit out of reach of open_csv() as it maust just open and not necassarily be responsible for content. So lets concentrate on (1) and (2).

In brief, @bakakaldsas you are testing (1), but the test is kind of self-fulilling with MockPath you wrote. From standard library you can use unittest.mock.mock_open() in MockPath to avoid creating custom-made open() method.

As for (2) one can also create a temp file, pass it to csv_open(), close/dekete file in teardown. I use that in https://github.com/epogrebnyak/mini-kep/blob/master/src/tests/test_finaliser_and_getter.py (with tempfile package to get temp dir/ tempfile).

What I'm doing in further commits is changing the structure of the submitted test and providing some new versions as described above.

# ERROR: approve all will fail on new definitons in 2009 4
Collection.approve_all()
ValueError: Missed labels: ['UNEMPL_pct', 'WAGE_NOMINAL_rub', 
'WAGE_REAL_yoy', 'WAGE_REAL_rog']    

Must check corresponding tab.csv file and edit spec.py parameters for these variables.

Комментарии к коммиту ниже:

• для чтения и дальнейшей отрисовки фреймов требуется минимальное преобразование данных на уровне pd.read_csv()
• сейчас годовой фрейм содержит только год, может содержать дату конца года и тогда для него не нужен специальный ридер, можно упросить, перегенерировав данные
• все время читать из интернета медленно, можно из других репозиториев позаимствовать класс, которые читает из интернета и сохраняет локальную копию, можно во временной папке, это ускоряет чтение CSV файлов

TODO: уточнить в репозиториях по нефти и курсу систему кэширования.

MER forecast at http://tinyurl.com/yaamhlhu

In src/exmple2.py will make an entry point for checks on resulting dataframes, based on following rules:

• absolute values by month/qtr accumulate to qtr/year (with tolerance)
• rog rates accumulate to yoy (with tolerance)
• other rules for consistency checks

Also it is a good point to transform GOV_ACCUM_variables to non-accumulated values (by substacting).