Package: laundry
Laundry: Folding spreadsheets into neat shapesSpreadsheets are easy to record and manipulate data with but do a poor job of displaying the data in an easy to read way. Laundry provides a simple way of converting spreadsheet data into Word files by by specifying the output document's format within the spreadsheet itself.Laundry provides two modes in which to generate the Word files:Single file mode, where details of a single output file are defined and passed at the CLI, andMulti file mode. where multiple output files can be defined and batched from a worksheet within the original Excel spreadsheet.While spreadsheets are, in many aspects, similar to database tables, Laundry is only a formatting tool and not a database.OverviewA general overview of how Laundry operates is:Having a spreadsheet containing some organised data stored in thedata_worksheet. There is no restriction on how the data stored is thedata_worksheetother than it must be a flat table.Defining the output structure within a separate worksheet contained within the spreadsheet. This is known as thestructure_worksheet.Thestructure_worksheetreferences data to be formatted by using the the data's column names, the styles contained within thetemplate_file, and how the data will be arranged, for example, as a table, paragraph or photo. Thestructure_worksheetdoes have a specific format that must be used to ensure that the conversion process takes place.Atemplate_fileWord document (.docxfile) is used as the basis of the output file. This file will contain the styles that will be used to format the output file.If a batch process is desired abatch_worksheetwill be required to define the above requirements.The app is run using the command line interface (CLI). This is as easy as:laundry single -t <template_file> <input_file> <output_file>, orlaundry multi <input_file>Running the AppLaundry is operated from the command line, so if you're not familiar with command line then you'll need to familarise yourself with it first.There are two ways of running Laundry, single mode and and multi mode.Single mode will convert a singledata_worksheetinto aoutput_filebased on thetemplate_fileusing the structure defined in thestructure_worksheet. You may need to define thedata-headerif the data is not in the first row of thedata_worksheet.Multi mode allows one or moreoutput_filesbased on information defined in theformat_worksheet. This mode still requires the same information as single mode but it is stored within a worksheet in theinput_file.ManualInput FileTheinput_fileis the spreadsheet that contains the data to be formatted and exported to theoutput_file.Theinput_filemustcontain worksheets that contain:The structure or output formatting requirements of the output file: this is thestructure_worksheet.When themultisub-command aformat_worksheetis required to allow the batch operation to take place.Theinput_file's data is stored in thedata_worksheet. This worksheet can be given any name provided it doesn't clash with thestructure_worksheetname.Structure WorksheetAstructure worksheetmust be defined for each output file that will be produced. Insinglemode the worksheet is assumed to be associated with thedata worksheetthat is passed to the app. Inmultimode a singlestructure worksheetcan be used for multiple output files, however it must be explicitly referenced for each output file.The following column namesmustimplemented in thestructure_worksheet. If they are not used the app will not work.section_typeThis defines the type of section that will be inserted with the output document. The top-to-bottom order will determine the order of the types in theoutput_file. The options that are currently supported are:para: This will insert a paragraph with the column header being the paragraph title styled using the style defined insection_style.table: Will insert a table that contains the data contained insection_containscell with the table column containing the same column heading as the original data (with any underscores removed).heading: Will use the data contained within the cell as a section heading made up of a title (column heading) and a paragraph (cell contents).photo: Inserts one or more photos (images) into the paragraph. Multiple images can be added by including them in thesection_containscolumn. Thephotocolumn heading is used to provide a file path to the directory containing the files. Including the photo's file extension is not required. The app will sequence through a number of popular formats before providing an error message to the standard output and adding the error message to the output document.section_containsThis contains one or more of the column names used in thedataworksheet. Multiple column names can be used withtableusingsection_typeprovided the are separated bynew lines(alt + enter) in the cell, or commas.new linesare the preferred method.section_styleThis Wordstylecontained within thetemplate_file's.docxfile. If this style is not in thetemplate_filethen Word's default styles will be used.This is a limitation of Word.title_styleThe Word formatting style to be used for titles within the document. This column does not apply to tables.section_breakMust be eitherTrueorFalse. IfTrueit will insert an empty paragraph provide a visual break between it and the following paragraph.page_breakMust be eitherTrueorFalse. IfTrueit will insert a page break (that is, start a new page) after the paragraph. This is useful for clearly separating information that is related to differentdata_worksheetrows.pathThis defines the relative file path to the directory (folder) containing the photos. All photos referenced in the cell must be stored in the same directory.section_typeLimitsEach of thesection_typetypes have some limit regarding their operation.Whereheadingis used it should be a single column heading per paragraph.Whereparagraphis used it should be a single column heading per paragraph.tablecan use any number of columns headings. Each column heading should be separated by anewline(\n) (preferred option) or by a comma (,).section_stylecanonly be a single value. This is a string (text) that can contain spaces. Make sure that the spelling and capitalisation is correct.title_stylecanonly be a single value. This is a string (text) that can contain spaces. Make sure that the spelling and capitalisation is correct.page_breakis aTrue/Falsevalue.Arranging Spreadsheet DataThe following applies to the bothsingleandmultisub-commands.data_worksheetThedata_worksheetcontains the data that will be formatted into theoutput_file.The column headers should be in row 0 (that is, the first row) in the worksheet. If not,When usingsinglesub-command the--data-headoption must to be used,andthe row number specified.  For example if the column headers start on row 5:laundry single -df=5 -t <template-file> <input-file> <output-file>When usingmultimode the row must be recorded in theheader rowcolumn.laundry multi -f <format-worksheet> <input-file>Do not use numbers for column header names. This will cause problems.Column header namesshouldavoid spaces, and either use underscores (_) or use camel case (ThisIsAnExampleOfCamelCase). Stick numbers at the end of the names if you need numbers in the name.If you want multiple paragraphs or bullet points, or more than one image, then use alt-enter in an Excel cell to allow this to take place.Include the file extension (for example.jpg,.png) when entering including images in the cell. File extensions are part of the file name and the app expects them to be included.structure_worksheetThe column headers must be in row 0 (that is, the first row) in the worksheet. If not, the app will not work.Thesection_typemust be one of the following:photoparatableheadingtablesections do not require a value fortitle_style.photosections do not require a value fortitle_styleorsection_style, however they do requirepathto be completed.section_breakandpage_breakmust beTRUEorFALSE.batch_worksheetThebatch_worksheetdefines the requirements for each of the output files. The spreadsheet will require a row for each file that is to be output.data_worksheetrequirementsThis is the name of thedata_worksheetthat contains the data to be exported as described above.structure_worksheetrequirementsThestructure_worksheetdefines how the output file will be structured. This is the same as described above.header_rowrequirementsThe number of the row that defines the header row in thedata_worksheet. This functionally identical to the-dhflag used with thesinglesub-command as described above.drop_empty_columnsrequirementsNot currently used.template_filerequirementsThe name of the.docxfile being used as the template for the output file. Different template files can be used provided that the are all stored in the directory that thelaundrycommand is run from.filter_rowsThis allows rows to be filtered from the output file by only including the rows that meet the criteria defined in the filter. More than one row can be specified to filter by.The row requires a particular format<row_heading>:<criteria1,...,criteriaN>. The heading row must be separated from the filter criteria by a colon (:). The filters criteriamustbe separated by commas (,), and each row must be separated by a newline (alt-enterin Excel).The filter criteria must beidenticalto the cell values. If the criteria can take different forms, that either:All forms must be included in the filter, orCorrect all the values so that they take common form (probably the better option).output_fileThe name of the file that is produced by the app. The file will be saved in the directory that the app is run from. The file name can be a relative or absolute file path.FAQsThe following is a list of commonly experienced issues.I get something containingKeyErrorand what looks like a column headerThe likely culprit is an incorrectly spelt column header in thestructure_worksheetor you haven't allowed for the conversion of underscores (_) replacing spaces within the column headers.Something likeNo sheet named <[some_worksheet_name]>Check thedata_worksheetandstructure_worksheetnames that you've used when running the app from the CLI. Check for spelling mistakes.Error: Invalid value for "input_file"appearsCheck the spelling of theinput_file's name and that the file path is correct. The app will check that theinput_fileexists before attempting to run the app.AttributeError: 'int' object has no attribute 'lower'The likely issue here is the column headers are not contained in the first row of thedata_worksheet. Also check that none of the column headers are numbers.Error: Invalid value for "--template" / "-t": Path "[some_path_&_filename].docx" does not exist.Thetemplate_filefilename is incorrect. This could also be the path to the file. Check both.I have a heap of formatted empty pages at the bottom of myconverted_file.For each row of yourdata_worksheetthat contains some data the app will produce a formatted section. By removing all the rows that you don't want at the bottom of thedata_worksheetyou can prevent this from occurring. There is a way to drop rows that are missing data, however this requires some work to enable this feature.KeyError: "no style with name '[some_Word_style]'"The Word formatting style is not present in thetemplate_file. Check that the style name matches exactly its name in Word.Some Word styles appear to be concatenations of other styles within Word, e.g. 'Heading 3, List'. These styles don't work as expected and the reason for this has not been determined.How do I use a specific Word style?Due to limitations with Word user specific styles need to be saved to  thetemplate_filefor them to be available. If the specified name is not present in thetemplate_filethen the app will not function.I want to create a single table from the data but every row has the header details: how do I remove the header details without using Word?This is a known problem, currently without a solution. A solution is being considered.