gtoolz

# ``gtoolz``

module documentation

Undocumented

Class | `MenuBox` | purpose: sets up a menu selection box executes selected function and arguments quits (returns) on "Enter" "Q" or "q" arguments: bclr: box color eg "reb" "blue" "green" clines: number of lines to center in the box center: center menu default is True methods: add_selection(["selection_name", func, arg1, arg2,...
Class | `Spinner` | purpose: prints a spinner in place input: msg="": str style='bar': ellipsis, pipe, box, vbar, growing_bar, missing_box, solid_box, arrow, clock, bar, balloons, moon, dot, braille, pulse prog|progressive|progress: bool color: str txt_color: str elspsed: bool requires: import sys import threading import itertools return: none use: with Spinner("Working...
Class | `ThreadWithReturn` | requires: import threading usage: run_cmd_threaded(cmd) which does this ... dbug("Just getting started...") cmd = "/home/geoffm/ofrd.sh" t1 = ThreadWithReturn(target=run_cmd, args=(cmd,)) t1...
Class | `Transcript` | Transcript - direct print output to a file, in addition to terminal. It appends the file target Usage: import transcript transcript.start('logfile.log') print("inside file") transcript.
Function | `add_content` | I wrote this because I am constantly building csv files with a header line consider add_or_replace() function Required: file content=str|list Options: after=pattern before=pattern replace=pattern position=## if none of those content is appended to the file if header is also included it will be added to the begining of the file if it does not already exitst used_to_be: add_line()...
Function | `add_or_replace` | purpose: Adds or replaces a line in a file where pattern occurs required: filename, action: str [before|after|replace|either] ,pattern, new_line action: before|after|replace|either (either will replace if it is found or add if it is not) options: - backup: bool=True, - ask: bool=False, - prnt: bool=False - centered: bool=False, - shadowed: bool=False pattern: needs to be unique regex...
Function | `askYN` | purpose: using msg as a prompt, this will ask for a simple Yes or No response and return a bool Typically used with an "if " statement but can simply be used as: askYN() options: - centered: bool - boxed: bool # puts only the prompt in a box with a reply prompt centered under it - timeout: int=0: int # how long to wait in seconds - auto: bool - exit: bool - quit: bool # if response is in ("q"...
Function | `askYN_demo` | purpose: demo of using askYN() function returns: None
Function | `bool_val` | purpose: look at args and kwargs with a list of possible option strings and return the default True or False requires: - key_l: str | list # this is the string or list of strings to check args and kwargs against options: - default | dflt: bool # the default value to return - opposite | opposites: str | list # a list of opposites eg: prnt = bool_val(["print", "prnt"], args, kwargs, dflt=True, opposites=['noprnt', 'no_prnt', 'no_print']) return True or False Notes: key_l can be a str or list args_l must be provided kvargs is optional used to see if a string or a list of stings might be declared true by being in args or seeing it has a bool value set in kvargs use: DBUG = bool_val('dbug', args, kvargs) or DBUG = bool_val(['dbug', 'DBUG'], args, kvargs)...
Function | `bool_val_demo` | Undocumented
Function | `boxed` | purpose: draw a unicode box around msgs args: msgs options: centered | center: bool # centers box on the screen prnt: bool txt_center: int # num of lines from top to center in the box color: str # text color box_color: str # color of border title, footer: str # goes in topline or bottom line centered of box width forces the width size defaults to # screen columns shadowed | shadow: bool # adds a shadow right and bottom...
Function | `boxed_demo` | purpose: demo of using boxed()
Function | `browseit` | purpose: opens the url in your browser requires: url: str returns: none
Function | `cat_file` | purpose: reads a file and return lines or rows_lol (list of list) or as a df (dataframe) options: - prnt: bool, # prints out the file contents - lst: bool, # returns a list of lines or you could use: txt...
Function | `centered` | purpose: calculates screen placement for msgs: list|str options: length=columns: int shift=0: int 'str'|'string'=False: bool 'lst'|'list'=True: bool returns: line|lines note: replaces deprecated centerit()...
Function | `centered_demo` | purpose: demo of using centered() returns: None
Function | `cfg_val` | purpose: to retrieve cfg val while allowing different key name request to get a specific key options: returns: value use: cfg_d = handleCFG("/path/to/api.cfg") api_key = cfg_val(["api", "key", "api_key"], 'testpypi', cfg_d, dflt="1234") # above will find the api_key if it is defined in the file with any of the names in the list for section='testpypi'...
Function | `chk_substr` | purpose: given a list of strings to check (chk_l) and a list of substrings to compare (strgs_l) if any "compare" substring is in any string in check list of strings then do action either 'exclude' or 'include' required: - chk_l: list | str - strgs_l: list options: - action: str # default is 'exclude' return: new_list usage: # given a list of functions, exclude the ones that have contain any of the substrings in the exclude_l list funcs_l = chk_substr(funcs_l, exclude_l, action='exclude')...
Function | `chkbox_demo` | purpose: chkbox() demo returns: None
Function | `chklst` | purpose: display a list of empty checkboxes|ballot boxes with chkd_l boxes checked and xed_l boxes with and X required: - my_l: list # list of check box names - chkd_l: list # list of boxes to be checked options: - dflt: str # default='empty' - alternatives: default= or dflt= 'chk', 'chkd', 'checked', 'all_chkd', 'chk_all , 'xed' 'x_all', 'all_x'...
Function | `chunkit` | purpose: break a list into a list of chunks - each chunk having size=size requires: my_l: list (eg boxes), size: int options: - full: bool # puts empty "cells" to make all "list chunks" the same number of elems - cols: bool # turn size into number of chunks or cols note: you can do this yourself eg size = len(my_l) // cols # where cols = number of columns <-- this method would probably less confusing returns: a list of lists(chunks) note: this is used: in a dashboard columns of boxes - see gcolumnize and in gtables...
Function | `cinput` | aka: centered input purpose: gets input from user using provided promt - centers the prompt on the screen options: - shift: int # allows you to shift the position of the prompt (from the center) eg shift=-5 - quit|exit|close: bool # will quit with do_close() if availaable or just sys...
Function | `clr_coded` | purpose: takes any msg string containing tags for colors and decodes them into a colorized string requires: msg_s: str returnd: colorized string decode a string - replace \[color\].*[\/] with code and reset requires a space before the first bracket...
Function | `clr_coded_demo` | purpose: demo of using clr_coded() returns: None
Function | `clr_demo` | purpose: color Demo - used for testing only
Function | `clr_tst` | purpose: This is strictly for developer testing strickly for developer use - given an ansi color CODE will display it in a way to see if it works as expected displays COLOR_TEST: This should be displayed using CODE returns: None...
Function | `cls` | purpose: Clears the terminal screen. returns: None
Function | `cnvrt2lol` | purpose: accepts any type of "data" (ie str|list|pandas|list of dictionaries|csv_file_name etc) and converts to a list of lists (ie lol) options: - colnames: list|str # list of colnames or string eg: "firstline"|"firstrow" declares that the firstrow is already the colnames - delimeter: char # if a filename is supplied (assumes a csv type file) this delimiter will be used to separate column values - index: bool # TODO - fix: bool # will "fix" all the rows of an lol to the length of the first row (be careful with this) - blanks: str|None # default=None blanks sets the string for elements added in row when fix option is used returns: a list of lists (rows of columns) with the first row having colnames...
Function | `cnvrt2lol_demo` | purpose: demo cnvrt2lol returns: None
Function | `columned` | purpose: set a list in X columns required: my_l: list options: - cols=0: int # number of columns - order='v': str # 'vertical', 'vert', 'v'| 'horizontal', 'hor', 'h' # order directs the order of the choices - proceed vertically through columns or horizontally through columns - justify='left: str # 'left', 'right', 'center' - prnt=False: bool # 'print', 'prnt'...
Function | `columned_demo` | purpose: to run a demo of using columned() options: None returns: None
Function | `comma_join` | purpose: given a list of elems or list or lists (of elems this function will turn each row into a proper comma delimited string or line The reason for this function is to take a list and make *sure* it is a proper csv list - with quoted elems as needed options: - newlines = bool - False # to be used if you want to add a newline to the end of the line(s) returns: a list of comma delimited strings (lines) typically used for csv notes: this has not been fully tested yet...
Function | `comma_join_demo` | purpose: demo of using comma_join() returns: None
Function | `comma_split` | purpose: split a line/str (or list of lines) using commas unless the comma is embedded in quotes returns: list (or list od lists) of comma separated elements notes: this is a kludge but it works for me...
Function | `comma_split_demo` | purpose: demo of using comma_split() return: None
Function | `cond_num` | purpose: this conditions (colorizes, rounds, and adds commas and unit indicators) elems if they are numbers input: elem options: "neg_color=red on black!": str, pos_color="green! on black!": str, rnd=0: int - color: bool # will color the number...
Function | `convert_temp` | expects a string with either an ending.lower() of "f" or "c" to declare what to return returns rounded(converted_temp) always returns a string with 2 places (inlcuding 0s)
Function | `dbug` | purpose: display DEBUG file, function, linenumber and your msg of local variable content required: xvar: str ... can be a local variable, a python statement, a string, a list options: -ask: bool # forces a breakpoint, stops execution ans asks the user before continuing -here: bool # will only return the DEBUG info (file, function...
Function | `dbug_demo` | purpose: A quick-n-dirty demo of using dbug()
Function | `ddbug` | purpose: this is for use by dbug only... as dbug can't call itself
Function | `display_in_cols` | deprecated as gtable may take it's place input: takes a list or a dict and prints in order across cols options: order default for list is is as-is if it is a dict you can sort "on" default "value" or on "key" , or reverse=True or reverse=False returns: lines (sorted if dict) example: # >>> lst = [*range(1,20)] # >>> display_in_cols(lst) then print lines eg printit(lines)...
Function | `do_close` | purpose: to provide a boxed closing message default msg is below options: - quote: str # should a random quote from filename provided be included - quoote_box_color: str # box color for quote default="White...
Function | `do_edit` | purpose: launches vim editor with file a quick-n-dirty utility to edit a file options: - lnum: line number Initiate edit on a file - with lineno if provided
Function | `do_func_demos` | purpose: allows selection of demos within this module - runs the demo function selected options: None return: None
Function | `do_func_docs` | purpose: to get function docs
Function | `do_logo` | purpose: presents a boxed logo for the begining of a program requires: nothing but you should provide some default content: str|list options: - content: str|list, - prnt: bool, - figlet: bool, - center: bool, - shadow: bool, - box_color: str, - color: str, - fotune: bool <-- requires the fortune app...
Function | `do_logo_demo` | purpose: demo of using do_logo() returns: None
Function | `do_prcnt_bar` | purpose: displays a percentge bar args: amnt (prcnt) options: full_range=100 if you submit this prcnt will be based on it - bar_width=40: int # declares width of bar - color: str # text color - done_color: # color of done portion - undone_color: # color of undone portion - done_chr: str # done character - undone_chr: str # undone character - prompt: str # prompt (before the bar) - suffix: str # suffix (afterr the bar) - brackets=["[", "]"]: list - show_prcnt=True: bool # include the percentage at the end - prnt=False: bool # False to allow use in dashboards # you can tell this to not print so you can include in in a box etc returns: percent bar line as a str #>>> rh = 56 #>>> rl = 50 #>>> cp = 51 #>>> amnt = cp - rl #>>> full_range = rh - rl #>>> print(f"rl {do_prcnt_bar(amnt,full_range)} rh") # rl [██████----------------------------------]16% rh...
Function | `docvars` | purpose: wrapper for function to allow variable substitution within its doc I use this in front on a function I call handleOPTS(args) which works with the module docopts Thank you to stackoverflow.com: answered Apr 25 '12 at 1:54 senderle this is a very useful way to allow variables in your __doc__ strings wrap a function with this and use if this way eg: @docvars(os...
Function | `dtree` | purpose: print a simple directory tree options: - files: bool # default=False - prnt: bool # default=False should we print out the lines - excludes: list | str # default=[] this is a pattern or list of patterns to skip - boxed: bool # boxes all the lines - length: int # default=3 # size of the "fill" returns: list (lines for printing)...
Function | `dtree_demo` | purpose: demo of using dtree()" return: None
Function | `escape_ansi` | purpose: Removes ansii codes from a string (line) returns: "cleaned no_code" line TODO: allow option to return clr_codes[1], nocode(elem), clr_codes[2] see: split_codes() aka: name should be escape_ansii...
Function | `file_exists` | purpose: returns bool if the file (or directory - see options) exists or is it executable options: type: str # Note: type can be "file" or "dir" (if it isn't file the assumption is dir) if type == "x" or "X" then the return bool will depend on if the file is executable returns: bool usage: file_exists('/etc/hosts') True...
Function | `find_file_in_dirs` | purpose: this is for future use as something like find_file_in_dirs(filename, dirs_l) notes: if dirs_l is empty it defaults to ["./"]
Function | `first_matched_line` | purpose: return: just the first matched line(s) from a filename using pattern required: - filename: str - pattern: str options: - upto: int default=1 # How many matching lines to return returns: matching lines...
Function | `fixlol` | purpose: makes the length or every "row" in a list of lists the same number of elements (length) options: - length: int # defaults to the length of the first row ie len(my_lol[0]) - blank: str|None # defaults to None but can be any string eg blank="...
Function | `flattenit` | purpose: "flattens nested lists options: none returns: list
Function | `from_to` | purpose: returns lines from a *file* from BEGIN pattern to END pattern" (between BEGIN and END) options: - include: can be equal to "none", top|begin|start, bottom|end, or 'both' -- include='top' will include the begin pattern line, -- include='bottom' will include the end pattern line -- include='both' will include top and end pattern matching lines returns: lines between (or including) begin pattern and end pattern from filename (or a list of lines)...
Function | `funcname` | purpose: returns current function name - primarily used for debugging
Function | `gblock` | purpose: justifies using nclen all strngs in msgs_l and maximizes each string length to the longest string - all lines will be the same length (nclen - no-color len) required: msgs_l: list # list of strings options: - height: int - length | width: int - pad: str # char to use for fill - position=1: str | list | int # eg: 'right center' or 'left top' (default) or [top, left] or 'middle bottom' or 1 (default) or 5 or 9...
Function | `gblock_demo` | purpose: demo of gblock() returns: None
Function | `gclr` | Purpose: to return color code + text (if any) NOTE: sub_color() uses this! input: text: str = "" # if "" then the color code alone is returned color: str = 'normal' # examples: 'red on black', 'bold green on normal', 'bold yellow on red', 'blink red on black' etc reset: bool # adds a color reset after the text Notes: color is the first argument because you may just want to return the color code only run gcolors...
Function | `gclr_demo` | purpose: demo of using gclr() returns: None
Function | `gcolumnize` | purpose: This will columnize (vertically) a list or a list of blocks or strings input: msg_l: list|lol options: - width|length=0: int # max width or use cols below - cols: int # number of desired columns - sep|sep_chrs|sepchrs=' | ': str # string or character to use between columns - prnt|print|show = False: bool - boxed: bool # box the output - box_color: str # color to use for box border - centered = False: bool # only invoked if prnt == True - title = "": str # only invoked if prnt == True - color: str - footer = "": str # only invoked if prnt == True - positions: list # list of either triplets or lists with 3 values, (row, col, position) --- position can easily be declared as 1-9 -> see gblock()...
Function | `gcolumnize_demo` | purpose: A demo of using gcolumnize Great for build quick dashboards
Function | `gcontains` | purpose: to determine if any pattern (str|list) is a substring of string (string_s) options: none returns: bool
Function | `get_boxchrs` | purpose: given a box_style (ansi, single, solid, double) will return a set of chars for creating a box input: box_style: str return: [tl, hc, ts, tr, vc, ls, rs, ms, bl, bs, br] as a list in the order shown Note: boxed() uses this tl = top_left, hc=horizontal_char, ts=top_separator, tr=top_right, vc=vertical_char, ls=left_separator, rs=right_separator, ms=middle_separator bl=bottom_left, bs=bottom_sep, br=bottom_right...
Function | `get_columns` | gets screen/terminal cols OR rows returns int(columns)| int(rows: bool) | int(cols), int(rows) both: bool
Function | `get_dtime_format` | purpose: returns the format of a date-time stamp string useful for date series in dataframes options: none returns date patters in strftime format
Function | `get_elems` | purpose: designed to split a list of lines on delimiter - respects quoted elements that may contain "," even if that is the delimiter - wip - this does the same thing as comma_split but adds a few options TODO Input: lines (as a list) options: - delimiter: str # (default is a comma) - col_limit: bool # max column size default=0 - if 0 no truncation occurs otherwise all elems are limited to col_limit - index: bool # will insert an index (line numbers starting with 0) # not used yet TODO - lst: bool # assumes a single line (ie: lines = str) so it returns a list of elemes from that line instead of a list_of_elems for multiple lines (ie an lol) Returns: an array: list of list (lol - lines of elements aka rows and columns) aka rows_lol...
Function | `get_elems_demo` | purpose: demo of get_elems() returns: None
Function | `get_html_tables` | purpose: to pull/scrape all tables off an url required: url requires: import pandas as pd from selenium import webdriver options: - show|prnt: bool # default=False ... whether to print the tables - spinner: bool # default=False...
Function | `get_html_tst` | purpose: to test get_html() options: start-maximized: Opens Chrome in maximize mode incognito: Opens Chrome in incognito mode headless: Opens Chrome in headless mode disable-extensions: Disables existing extensions on Chrome browser disable-popup-blocking: Disables pop-ups displayed on Chrome browser make-default-browser: Makes Chrome default browser version: Prints chrome browser version disable-infobars: Prevents Chrome from displaying the notification ‘Chrome is being controlled by automated software...
Function | `get_mod_docs` | purpose: lists all functions and the docs from a module Note: except some functions eg _demo returns cnt
Function | `get_random_line` | purpose: grabs one random line from a file requires: from this_file purify_file, centered, boxed, printit, cat_file import random file: str | list # can be a filename or it can be a list of lines returns: line Note: file has all comments removed first (purified)...
Function | `gline` | purpose: prints a line with msg and options: - width: int, - msg|title: str # default="" msg has to be a key=val pair! eg: gline(60, msg="My Message", just='center') - fc: str # default=" " fill string/character (char(s) used to fill all surrounding space default: lc=rc=fc) - lc: str # default=fc left/edge/corner (char(s) for left corner ie first charater(s)) - rc: str # default=lc right/edge/corner (char(s) for right corner ie last charcter(s)) - pad: str # default="" string/character(s) on each side of msg - lpad: str # default=pad - rpad: str # default=lpad - box_color: str - color: str - lfill_color: str - rfill_color: str - just: str # default = "left"|"l" but can be declared "center"|"c" or 'right'|"r" - prnt: bool # prints the output returns: line: str...
Function | `gline_demo` | purpose: demo of using gline() returns: None
Function | `grep_lines` | purpose: searches lines (or file if lines is a filename) for pattern options: - ic: bool (insensitive case) - rtrn_bool=False: bool # (whether to rtrn lines [default] or bool result) - csv: bool # will convert a list of lists to a list of csv style lines before searching - # and but returns the line as a list, just the way we got it returns: matched line(s) (or True False if rtrn_bool is True) Note: if only one line is matched then it will return that one line otherwise it will return a list of matched_lines...
Function | `gselect` | purpose: menu type box for selecting by index, key, or value required: - selections: list or dictionary options: - prompt: str # no need to include ": " - rtrn='' # can be 'k|key' or 'v|val|value' or "i" | "int" <-- tells gselect whether you want it to return a key or a value from a supplied list or dictionary or just user input (default) # if "i"|"int" is invoked then the value of the key will return as an integer (as opposed to a string) This is an important option and allows control over what gets returned...
Function | `gselect_demo` | demo of using gselect
Function | `gtable` | purpose: returns lines or displays a colorized table from a list_of_lists, df, or dictionary input: rows: str|list|dict|list_of_lists|list_of_dicts|dataframe options: - color: str, - box_style: 'single', 'double', 'solid', - box_color: str, - header|hdr: bool, # header | hdr # highlights the colnames - end_hdr: bool # adds highlighted hdr/colnames to the bottom of the table - colnames: list | str, 'firstrow' | 'firstline' | 'keys' - col_colors: list, # gtable will use this list of colors to set each column, repeats if more cols than colors - neg: bool | list, - nan: str, - alt: bool_val, - alt_color: str, - title: str, - footer: str, - indexes: bool, - box_style: str, - max_col_len|col_limit|col_len...
Function | `gtable_demo` | purpose: test/demo using gtable() returns: None
Function | `gtitle` | purpose: quick-n-dirty Title/Separation Line - I use this just to separate sections returns: prints a line with "=" fill character and msg in the middle (centered) with width=width see: gline_demo
Function | `handleCFG` | purpose: if no cfg_file given it will find the default and return cfg_d (dictionary of dictioanries: cfg.sections; cfg.elem:vals) input: cfg_file: str defaults: cfg_file if it exists is: {myappname.basename}...
Function | `handleOPTS` | Usage: {0} [-hEP] [--dir] [<filename>] {0} -s <func> {0} -S <func> {0} -t [<func>] {0} -T <func> [<fargs>] {0} --version
Function | `has_alnum` | purpose: test whether a string is all alpha numeric Is a string blank or all white space... isspace() does the samething
Function | `has_substr` | purpose: determin if any sub-string in chk_l is in text_s column_name = "dtime" eg is "time" or "date" in column_name... then use has_substr(column_name, ["time", "date"]) required: - text_s: str - chk_l: list options: - ci: bool # case_insensitive returns True | False used in quick_plot()...
Function | `ireplace` | purpose: index replace To get indices use eg: iter = re.finditer(rf"{c}", s) indices = [m.start(0) for m in iter] # next line removes first two and last two indices - just an example indices = indices[2:-2] then use this func with: s: is the string to do the replacements indices: list of indexed positions char: is the char to replace with...
Function | `isempty` | purpose: tests if a variable is empty ie len(my_var) == 0 or my_var is None etc options: None returns: bool
Function | `islod` | purpose: is this a list of dictionaries options: None returns: bool
Function | `islol` | purpose: determine is my_lol is actually a list of lists required: list - my_lol options: none return: bool True | False
Function | `islols_demo` | purpose: to demonstatrate islol and islos functions required: none optons: none return: none
Function | `islos` | purpose: determines if my_los is a list of strings returns: bool
Function | `isnumber` | purpose: determines if x is a number even if it is a percent, or negative, or is 2k or 4b or 10M etc or test for stricktly float options: - float: bool # is this a float - human: test the submission after stripping off "human" symbols like "M" or "G" or "%" etc input: x: str|float|int returns: True|False notes: tests...
Function | `isnumber_demo` | purpose: test/demo of using isnamber() returns: None
Function | `key_swap` | purpose: switch or change the keyname (a single key) on an element in a dictionary args: orig_key # original key name new_keyA # new key name d # dictionay to change returns: the altered dictionary...
Function | `kv_cols` | input: my_d: dict cols:default=3 <-- both args ie: dict and cols are required! options: - title, header, pad, box_style, box_color: str, color: str, neg: bool, - prnt: bool, footer,title: str, rjust_cols: list, sep,pad: str, max_col_width: int, - centered: bool, box_style: str, human: bool, rnd: bool, box_title: bool (requires title), sep: str - hdr: bool default=True - no_hdr: bool # removes hdr/colnames from tables returns: lines tabalized key-value pairs...
Function | `kv_cols_demo` | purpose: demo of using kv_cols() returns: None
Function | `kvarg_val` | purpose: returns a value when the key in a key=value pair matches any key given NOTE: key can be a string or a list of strings option: dflt="Whatever default value you want" use: used in function to get a value from a kwargs ky=value pair - eg: def my_function(*args, **kwargs): txt_center = kvarg_val(["text_center", "txt_cntr", "txtcntr"], kwargs, dflt=1) - so if you call my_function(txt_center=99) then txt_center will be set to 99 --- If any key in the list is set = to a value, that value is returned see: bool_val which process both args and kvargs and returns bool_val input key(string), kvargs_d(dictionary of key,vals), default(string; optional) purpose: return a value given by a key=value pair using a matching key (in key list if desired) options: - key provided can be a string or a list of strings - dflt="Whatever default value you want - can be a string, list, int, float...
Function | `kvarg_val_demo` | WIP
Function | `lineno` | purpose: returns current line number - primarily used for debugging
Function | `list_files` | purpose: prints a list of enumerated basename filenames (sorted by name) input: dirs=list|str options: pattern: str|list = "*" # glob pattern return_msgs<bolean> = False prnt<bolean> = False dirs: bool # include dirs dir_only: bool # only dirs links: bool # include links returns: a sorted list of those names or return_msgs and sorted names use: list_files("/tmp")...
Function | `long_proc` | purpose: this is only for test or demos - it nothing but a sleep
Function | `main` | purpose: allows user to see some of the fuctionality of this tool set
Function | `matrix` | purpose: initialize a matirx (ie array) required: rows/dim1: int, cols/dim2: int options: - dflt_val=None: anything # default "value" to initialize each "cell" to returns: 2 dim initialized array/matrix aka: init_arr | initarray | init_arr...
Function | `max_width_lol` | purpose: to determin max_width for each "column" in a list of lists this is a way of truncating "columns" returns: column sizes
Function | `maxof` | purpose: returns length of longest member of a list (after escape_ansii codes are removed) required: list or list_of_lists (lol) options: - length|len|max_len|elem_len: bool # default=True longest length is returned - height|rows|max_height|row_len: bool # default=False largest number of elements in list (typically the number of lines in a list of strings) - elems: bool # default=False in a list of lists this will rerturn the greatest number of elements in each member of a list (see note below) - lst: bool # default=False returns a list which will be the max length(s) or height(s) of each elem in a list returns: int max length of eleemes note: saves me from having to look up how to do this all the time and works with lists or lists of list - sometimes I need to know the number of rows in cols (lol of rows in cols ie: cols_lol = [row1, row2], [row1, row2, row3], [row1, row2]]...
Function | `maxof_demo` | purpose: Demos of using ruleit() function returns: None
Function | `nclen` | purpose: finds the length of a string minus any ansi-codes and returns that lenght returns: length aka: no_color len of line (length w/o ansii codes)
Function | `pp_d` | purpose: pretty print a dictionary deprecated as gtable does this with between (str) placed between elems and kv_s (str) between k and v >>> d = {"one": 1, "two": 2, "three": 3} >>> print(pp_d(d)) one: 1 two: 2 three: 3...
Function | `printit` | purpose: prepares and prints (option) msg: str|list and can put in unicode color box, centered in terminal and with color required: msg: str|list (can contain color codes (see below) options: "boxed" | boxed=False # prepares a box around msg "centered" | centered=False # centers horizontally msg on a termial screen "shadowed" | shadowed=True # adds a shadow typically around a box "prnt" | prnt=True # print line(s) or just return them as a str (useful for input(printit("What do you want...
Function | `printit_demo` | purpose: demo of using printit() returns: None
Function | `progress` | purpose: displays a progress bar typically used within a loop options: - width - prompt - color - done_color - undone_color - prnt - COLOR - DONE_COLOR - UNDONE_COLOR - RESET - done_chr - undone_chr - status - center_b - shift: returns: none # prcnt = 0...
Function | `purify` | purpose: de-comments a file, aka removes all comments denoted by "#" ... input: file: str return lines: list (decommented lines)
Function | `pyscraper` | I may deprecate this as I rarely use it example: pat # pat = '<span class="Trsdu\(0.3s\) Fw\(b\) Fz\(36px\) Mb\(-4px\) D\(ib\)" data-reactid=".*?".*?>.*?</span.*?>' # noqa: Be careful... pay attention to the html page when using a script...
Function | `quick_plot` | purpose: quick display of data in a file or in dataframe displays a plot on a web browser if requested required: data: df | str | list (filename: csv or dat filename) options: - show | prnt: bool - centered: bool - title: str - footer: str - tail: int # for the last n rows of the df default=35 - choose: bool # invokes gselect multi mode to allo"w selections of columns to display in the plot (graph) - selections: list # you can declare what columns to plot - web: bool # displays to your browser instead of a plot figure - dat: bool | str # I sometimes use a commented firstline for headers - # using 'dat' declares this to be true, if character is used ie dat=":" # then that will be used as the delimiter - type: str # default=line, bar, barh, hist, box, kde, density, area, pie, scatter, hexbin - colnames: list | str # default = [] if it is a str="firstrow" then the firstrow obviously will be treated as colnames - mavgs: bool # 50 day and 200 day moving averages added to plot - box_text: str | list # string or lines to add to a box in fuger default="" - subplot: str # sub plot with area under filled using column name = subplot - save_file: str # name of file to save the plot figure to...
Function | `quick_plot_demo` | purpose: to provide examples of displaying data in plots returns: None
Function | `reduce_line` | purpose: reduce a line to no more than max_len with and no broken words then return the reduced_line, and remaining_line returns: tuple - this_line(reduced) and the remaining part of the line Note - used in wrapit()...
Function | `regex_col` | regex for a patern in a word|column file_lines can be a filename or lines (list) col starts at 0 to be consistent with coding standards returns lines where pat matches col number word ie words[col]
Function | `remap_keys` | purpose: remaps keys names AND can select only the k.v pairs you want (in the order specified) (ie option: 'mapped_only') options: - mapped_only: bool, - rnd: int # rounds out numbers to rnd scale returns: my_d (remapped and optionally selected pairs) notes: remap_d should be dict {orig_key: new_key,...
Function | `replace_all` | purpose: replaces every dict key with dict value in a string with_d eg: {' ', ' ', 'foo', 'bar'} returns: str TODO need more doc info here
Function | `retry` | purpose: a wrapper to retry a function x (howmany) times notes: there is a module called retrying that deserves more research and it provides a wrapper function called @retry() useage: eg: @retry(5, MySQLdb...
Function | `rgb` | purpose: translated rgb(r,g,b) text into ansi color CODE input: r, g, b, text prfx: bool = False bg: bool = False # if set to true the color is applied to bg returns: rgb color coded text
Function | `rootname` | purpose: returns the root name of a full filename (not path, no extension) input: filename: str returns: ROOT_NAME: str
Function | `rowscols_cols` | purpose: this takes a longish lol - namely, rows of columns and allows you to split those rows into X columns. This is most likely used to split up rows of columns for gtables so an option include colnames to add to the top of each new column of rows cols: This is an experiment but I think it could be useful Here is a simple visual row_of_cols +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ split_tables = rowscols_cols(row_of_cols, 2) +------+-----+----+ +------+-----+----+ | | | | | | | | +------+-----+----+ +------+-----+----+ | | | | | | | | +------+-----+----+ +------+-----+----+ | | | | | | | | +------+-----+----+ +------+-----+----+ | | | | +------+-----+----+ TODO...
Function | `ruleit` | purpose: This is for development purposes It draws a rule across the screen and that is all it does It fails to prepare your meals or schedule your week's agenda, sorry. options: - width: int # default=0 - truncates at this len otherwise it is screen length - cntr: bool # default=False - provide center info - prnt: bool # default=True - whether to print returns: printed ruler line with tick marks and marker numbers below...
Function | `ruleit_demo` | purpose: demo of using ruleit() returns: None
Function | `run_cmd` | purpose: runs cmd and returns output eg: out = run_cmd("uname -o",False) # now you can print the output from the cmd: print(f"out:{out}") options: - lst: bool # ouput will return as a list of line rather than a str - rc: bool # returns the cmd return code instead of output - both: bool # returns (output, rc) - runas: str # you can declare who to run the cmd as - prnt: bool # print output - returns None returns: output from command Note: if runas == sudo then the command will be sun with sudo...
Function | `run_cmd_demo` | purpose: demo of run_cmd(cmd) returns: None
Function | `run_cmd_threaded` | purpose: runs a cmd as a thread options: - lst: bool # returned output lines will be put into a list rather than a str return: output from cmd Note: Please, be aware that a result will be returned only after this finishes so put it "later" rather than "sooner" in your app - does not currently return error msgs...
Function | `sayit` | purpose: This will use computer voice (espeak) to "say" the msg options - prnt: will print as well # this is very limited - gender: str # m | f - volume: float # 0 - 1 - rate: int # default = 150 - tone: int # 1 - 5 <-- this does not seem to do anything...
Function | `sayit_demo` | purpose: demo of using sayit() returns: None
Function | `select_file` | purpose: select a file (or dir) from using pattern(s) required: options: - path: str|list (defaults to "./") - pattern: str|list - prompt: str - mtime: bool # include mtime in listing - centered - dirs: bool # include dirs - dirs_only: bool # only directories - prnt: bool - shadow - footer - width=0 use: f = select_file("/home/user","*...
Function | `shades` | purpose: returns a list of increasing intensity color shades requires = color: str options: - num=16 <-- number to divide into 255 ~ the number of color intensities - rtrn??? TODO return codes or text...
Function | `shadowed` | purpose: adds shadowing typically to a box requires: input: lines as a list output: lines as a list Use this to see all the styles: msg = "this is my message" for n in range(0,5): printit(centered(shadowed(boxed(msg + f" style: {n}"),style=n))) ...
Function | `sorted_add` | purpose: to insert a line between two patterns in a sorted way insert line into filename between after and before patterns the patterns need to be regex ie: r"pattern" assumes the block from after to before is sorted returns: new_lines eg: line = 'Insert this line (alphabetically) after "^-alt" but before "^-[a-zA-Z0-9] within block' filename = "/home/geoffm/t...
Function | `Spinner_demo` | purpose: demo of Spinner
Function | `split_codes` | purpose: to split out ansi codes and return them input: elem: str (that contains ansi codes for color) options: TODO include elem dflt=False returns: codes: list (unless elem=True [or 'with_elem' or 'asdict'], then it is a dictionary with preffix, elem, and suffix as key/value pairs) notes: - used in cond_num() aka: color_neg() - NOTE: this function expects both a prefix code and a suffix code...
Function | `split_codes_demo` | purpose: test/demo of splitting ansii code away from a string returns: None
Function | `splitit` | purpose: given a string (s), split it using delimiter which can be a string or regex requires: import re input: - s: str # string to split - delimiiter=" ": str options: none returns: phrases: list # string split into elements notes: eg: delimiter = r"["|'] +[-–—―] +" # amazingly all those dashes are different symbols...
Function | `sub_color` | purpose: substiture ansi color CODE for given color returns ansi-CODE
Function | `transcript_demo` | Undocumented
Function | `transcript_start` | Start class Transcript(object=filename), appending print output to given filename
Function | `transcript_stop` | Stop class Transcript() and return print functionality to normal
Function | `try_it` | BROKEN BROKEN BROKEN This is a wrapper function for running any function that might fail - this will report the error and move on use: @try_it def my_func(): print("if this failed an error would be reported ") my_func()...
Function | `try_to_get` | may deprecate this as I rarely use it This is for use with selenium requires: from selenium import webdriver from selenium.webdriver.common.keys import Keys from selenium.webdriver.common.by import By from selenium...
Function | `tst` | purpose: for development one testing only - subject to change at anytime returns: None notes: This is for testing only This is just an example testing function. This example shows how you can quickly test whatever you want (any function) while you are still editing a file...
Function | `usr_input` | purpose: allow user input with editing options:: - prompt: str = "Your input: " - edit: bool - dft: str - centered: bool - shift: int - update: dict - length: int = 0 # all lines will display with the same length returns: edit or input data as str or dict if update option Notes: - this function is typically called by usr_update() - see usr_update()...
Function | `usr_input_demo` | purpose: demo of usr_input() returns: None
Function | `usr_update` | purpose: given a dict, and a list of keys to change - allow user update(s) to values in my_d dictionary go through the list of keys to fix and prompt user for new value, present the current value as default args: my_d: dict # dict to have updated options: - fix: list # default=[] - list of keys to prompt user for change; if empty, use all the my_d keys - centered: bool # default=False - whether to center everything on the screen - edit: bool # defualt=False - whether to allow text edit in place or the default of input replacement input - no_edits: list # default=[] - list of keys that are presented but not editable - quit: bool # default=False - whether to immediately quit on an entry of "q" or "Q", or "quit" returns: my_d (with user updates) Notes: - what is in the passed dict values is what will be presented as the default...
Function | `usr_update_demo` | purpose: demo for usr_update() return: None
Function | `wrapit` | purpose: turns line(s) into a list of strings with full words less than or equal to length input is sentence which can be a string or list returns lines list wrapped using length and color if provided NOTE: all color codes will get stripped out before processing requires import of wrapper...
Function | `wrapit_demo` | purpose: demo of using wrapit returns: None
Function | `write_file` | purpose: writes data to a file typically as a csv file (or a .dat file) - creates a new file or appends an existing file options: - colnames: list (adds hdr line if not currently there) - comment_lines: str | list - bak: bool # make a backup file - indx: bool # not used yet - future flag for adding an index col (first column) or not - prnt: bool # turns on print - ask: bool # ask before actually writing data to file (before overwriting the file) - append: bool # whether to append data - the default=False whereby submitted data will overwrite the file - dat: bool # this is a special flag to declare that the first line (hdr) is made a comment starting it with "#" returns: bool # true if successful write Notes: - only use this to write a data file = either csv (or a dat file which is a csv file with the header commented) - data should be a list of lists (rows of cols) - assumes first line is comma delimited colnames or use colnames option (in a dat file the first line will be commented) - all comments will go to/near the top - if the file ends with the "...
Function | `xlate_clr` | purpose: translates special color names to rgb(r,g,b) for processing requires: special color eg: - greyXX | grayXX # where XX is a precent gradient of gray from 0,0,0 for black! to 255,255,255 white - white...
Constant | `BLACK` | Undocumented
Constant | `RESET` | Undocumented
Constant | `SCRIPT` | Undocumented
Variable | `__version__` | Undocumented
Variable | `bg_colors_d` | Undocumented
Variable | `dtime` | Undocumented
Variable | `fg_colors_d` | Undocumented
Variable | `styles_d` | Undocumented

def add_content(file, content='', header='', **kvargs):

I wrote this because I am constantly building csv files with a header line consider add_or_replace() function Required: file content=str|list Options: after=pattern before=pattern replace=pattern position=## if none of those content is appended to the file if header is also included it will be added to the begining of the file if it does not already exitst used_to_be: add_line()

def add_or_replace(filename, action, pattern, new_line, *args, backup=True, **kwargs):

purpose: Adds or replaces a line in a file where pattern occurs required: filename, action: str [before|after|replace|either] ,pattern, new_line action: before|after|replace|either (either will replace if it is found or add if it is not) options: - backup: bool=True, - ask: bool=False, - prnt: bool=False - centered: bool=False, - shadowed: bool=False pattern: needs to be unique regex? returns: "done" or None depending on use

def askYN(msg='Continue', *args, dflt='y', center=False, auto=False, **kwargs):

purpose: using msg as a prompt, this will ask for a simple Yes or No response and return a bool Typically used with an "if " statement but can simply be used as: askYN() options: - centered: bool - boxed: bool # puts only the prompt in a box with a reply prompt centered under it - timeout: int=0: int # how long to wait in seconds - auto: bool - exit: bool - quit: bool # if response is in ("q". "Q") an sys.exit() is executed - dflt: str="y" # the default is "y" - auto: bool # var can be used to automatically invoke the default - shift: int # will shift prompt left (neg) or right (pos) returns: bool # True or False useage: askYN() Continue [y]: True or if askYN("Do you want to save this file?", "n"): do_save_file()

def askYN_demo():

purpose: demo of using askYN() function returns: None

def bool_val(key_l, args_l, kvargs={}, **kwargs):

purpose: look at args and kwargs with a list of possible option strings and return the default True or False requires: - key_l: str | list # this is the string or list of strings to check args and kwargs against options: - default | dflt: bool # the default value to return - opposite | opposites: str | list # a list of opposites eg: prnt = bool_val(["print", "prnt"], args, kwargs, dflt=True, opposites=['noprnt', 'no_prnt', 'no_print']) return True or False Notes: key_l can be a str or list args_l must be provided kvargs is optional used to see if a string or a list of stings might be declared true by being in args or seeing it has a bool value set in kvargs use: DBUG = bool_val('dbug', args, kvargs) or DBUG = bool_val(['dbug', 'DBUG'], args, kvargs)

def bool_val_demo():

Undocumented

def boxed(msgs, *args, cornerchr='+', hchr='=', vchr='|', padmin=1, color='', title='', footer='', style='single', shadow=False, **kwargs):

purpose: draw a unicode box around msgs args: msgs options: centered | center: bool # centers box on the screen prnt: bool txt_center: int # num of lines from top to center in the box color: str # text color box_color: str # color of border title, footer: str # goes in topline or bottom line centered of box width forces the width size defaults to # screen columns shadowed | shadow: bool # adds a shadow right and bottom ... some other options; see below returns boxed lines: list NOTES: this function does not print - it returns the box lines

def boxed_demo():

purpose: demo of using boxed()

def browseit(url):

purpose: opens the url in your browser requires: url: str returns: none

def cat_file(fname, *args, prnt=False, lst=False, **kwargs):

purpose: reads a file and return lines or rows_lol (list of list) or as a df (dataframe) options: - prnt: bool, # prints out the file contents - lst: bool, # returns a list of lines or you could use: txt.split(' ') to make it a list - csv: bool, # treat the file as a csv (or for me, a dat file) - dat: bool, # this one will seem strange, it treats the first line as a commented out header line - xlsx: bool, # returns df of a spreadsheet file - hdr: bool, # whether to include header line or header data in the return - df: bool, # return a df - delimiter: str # delimiter to use for a csv, or dat file - rtrn: str, (can be "str", "string", "lst", "list", "df" - nums: bool # forces all numbers to be returned as floats instead of str - useful for plotting - index: bool # adds id numbers to csv data returns the text of a file as a str or rows_lol (if it is a cvs: bool file) or returns a df if requested Note: if the result df has the header/colnames repeated in row[0] then make sure you included 'hdr' or hdr=True #>>> t = cat_file("/etc/timezone") #>>> print(t) America/New_York <BLANKLINE>

def centered(msgs, *args, **kwargs):

purpose: calculates screen placement for msgs: list|str options: length=columns: int shift=0: int 'str'|'string'=False: bool 'lst'|'list'=True: bool returns: line|lines note: replaces deprecated centerit()

def centered_demo(*args, **kwargs):

purpose: demo of using centered() returns: None

def cfg_val(keys, section, cfg_d, dflt=''):

purpose: to retrieve cfg val while allowing different key name request to get a specific key options: returns: value use: cfg_d = handleCFG("/path/to/api.cfg") api_key = cfg_val(["api", "key", "api_key"], 'testpypi', cfg_d, dflt="1234") # above will find the api_key if it is defined in the file with any of the names in the list for section='testpypi'

def chk_substr(chk_l, strgs_l, action='exclude'):

purpose: given a list of strings to check (chk_l) and a list of substrings to compare (strgs_l) if any "compare" substring is in any string in check list of strings then do action either 'exclude' or 'include' required: - chk_l: list | str - strgs_l: list options: - action: str # default is 'exclude' return: new_list usage: # given a list of functions, exclude the ones that have contain any of the substrings in the exclude_l list funcs_l = chk_substr(funcs_l, exclude_l, action='exclude')

def chkbox_demo(*args, **kwargs):

purpose: chkbox() demo returns: None

def chklst(my_l, chkd_l=[], *args, **kwargs):

purpose: display a list of empty checkboxes|ballot boxes with chkd_l boxes checked and xed_l boxes with and X required: - my_l: list # list of check box names - chkd_l: list # list of boxes to be checked options: - dflt: str # default='empty' - alternatives: default= or dflt= 'chk', 'chkd', 'checked', 'all_chkd', 'chk_all , 'xed' 'x_all', 'all_x' ... - xed: list # list of elems to "X" - boxed: bool - centered: bool - prnt: bool - color|clr: str # default="" - text color - masterbox_clr: str # default='white! on black' - outside master box color - chkmark_clr: str # default='green!' - check mark color - xmark_clr: str # default='red!' - X mark color - chkbox_color: str # default="" - check boxes color - title: str - footer: str - cols: int # number of columns - indx|nums|indexed|numbered: bool # whether to number the items returns: list # printable lines notes: use: ans = [] my_l = ["one", "two", "three"] chkd_l = [] while ans not in ("q", "Q", ""): cls() chklst(my_l, chkd_l, 'prnt', 'centered', 'boxed', title="What has been done", footer=dbug('here')) ans = gselect(my_l, centered=centered_b) chkd_L.append(ans)

def chunkit(my_l, size, *args, **kwargs):

purpose: break a list into a list of chunks - each chunk having size=size requires: my_l: list (eg boxes), size: int options: - full: bool # puts empty "cells" to make all "list chunks" the same number of elems - cols: bool # turn size into number of chunks or cols note: you can do this yourself eg size = len(my_l) // cols # where cols = number of columns <-- this method would probably less confusing returns: a list of lists(chunks) note: this is used: in a dashboard columns of boxes - see gcolumnize and in gtables

def cinput(prompt, *args, **kwargs):

aka: centered input purpose: gets input from user using provided promt - centers the prompt on the screen options: - shift: int # allows you to shift the position of the prompt (from the center) eg shift=-5 - quit|exit|close: bool # will quit with do_close() if availaable or just sys.exit() returns: user response

def clr_coded(msg_s):

purpose: takes any msg string containing tags for colors and decodes them into a colorized string requires: msg_s: str returnd: colorized string decode a string - replace \[color\].*[\/] with code and reset requires a space before the first bracket

def clr_coded_demo(*args, **kwargs):

purpose: demo of using clr_coded() returns: None

def clr_demo():

purpose: color Demo - used for testing only

def clr_tst(CODE, color='unknown'):

purpose: This is strictly for developer testing strickly for developer use - given an ansi color CODE will display it in a way to see if it works as expected displays COLOR_TEST: This should be displayed using CODE returns: None

def cls():

purpose: Clears the terminal screen. returns: None

def cnvrt2lol(data, *args, **kwargs):

purpose: accepts any type of "data" (ie str|list|pandas|list of dictionaries|csv_file_name etc) and converts to a list of lists (ie lol) options: - colnames: list|str # list of colnames or string eg: "firstline"|"firstrow" declares that the firstrow is already the colnames - delimeter: char # if a filename is supplied (assumes a csv type file) this delimiter will be used to separate column values - index: bool # TODO - fix: bool # will "fix" all the rows of an lol to the length of the first row (be careful with this) - blanks: str|None # default=None blanks sets the string for elements added in row when fix option is used returns: a list of lists (rows of columns) with the first row having colnames

def cnvrt2lol_demo(*args, **kwargs):

purpose: demo cnvrt2lol returns: None

def columned(my_l, *args, **kwargs):

purpose: set a list in X columns required: my_l: list options: - cols=0: int # number of columns - order='v': str # 'vertical', 'vert', 'v'| 'horizontal', 'hor', 'h' # order directs the order of the choices - proceed vertically through columns or horizontally through columns - justify='left: str # 'left', 'right', 'center' - prnt=False: bool # 'print', 'prnt' ... to invoke printing the lines - boxed: bool - centered: bool - title: str - footer: str - width=0: int # cols will be calculated from this - approximated returns: lines for printing notes: this takes the place of standard module columnize so we are not dependant on that code - you probably do not want to use this function directly - use gcolumnize instead. used by: gcolumnize()

def columned_demo():

purpose: to run a demo of using columned() options: None returns: None

def comma_join(data, *args, **kwargs):

purpose: given a list of elems or list or lists (of elems this function will turn each row into a proper comma delimited string or line The reason for this function is to take a list and make *sure* it is a proper csv list - with quoted elems as needed options: - newlines = bool - False # to be used if you want to add a newline to the end of the line(s) returns: a list of comma delimited strings (lines) typically used for csv notes: this has not been fully tested yet

def comma_join_demo(*args, **kwargs):

purpose: demo of using comma_join() returns: None

def comma_split(my_s, *args, **kwargs):

purpose: split a line/str (or list of lines) using commas unless the comma is embedded in quotes returns: list (or list od lists) of comma separated elements notes: this is a kludge but it works for me

def comma_split_demo(*args, **kwargs):

purpose: demo of using comma_split() return: None

def cond_num(elem, *args, **kwargs):

purpose: this conditions (colorizes, rounds, and adds commas and unit indicators) elems if they are numbers input: elem options: "neg_color=red on black!": str, pos_color="green! on black!": str, rnd=0: int - color: bool # will color the number ... default red for negative and green for positive - neg_color: str # you can change the color for negative numbers - pos_color: str # you can change the color for positive numbers - rnd: int # if rnd == "" nothing will be done, if rnd is 0 it will make elem an integer, if rnd > 0 then that will be used for the number of places to round - human: bool # adds reduces large numbers to 10000000 to 1M etc - nan: str # allows you to change "nan" or "NaN" to any string you want. default="" returns: elem (conditioned; colored) use: - for n, row in enumerate(lol): - ... - if neg: - row = [color_neg(elem) for elem in row] - # table.add_row(*row) - table_lol.append(*row) NOTE: this may return an elem with a different length aka: color_neg(elem)

def convert_temp(temp, convert2='f'):

expects a string with either an ending.lower() of "f" or "c" to declare what to return returns rounded(converted_temp) always returns a string with 2 places (inlcuding 0s)

def dbug(xvar='', *args, exit=False, ask=False, prnt=True, **kwargs):

purpose: display DEBUG file, function, linenumber and your msg of local variable content required: xvar: str ... can be a local variable, a python statement, a string, a list options: -ask: bool # forces a breakpoint, stops execution ans asks the user before continuing -here: bool # will only return the DEBUG info (file, function. linenumber) as a string without printing - typically used like this boxed("my box", footer=dbug('here')) -boxed: bool # boxes debug output -box_color: str # declares box_color default is 'red! on grey40' -color: str # declares text output color -centered: bool # centers the debug output -lst: bool # forces printing the variable contents as a list (like printit()) - allows displaying ansii codes properly -titled: bool # only works when 'boxed'... puts the DEBUG info into the title of a box This should probably be the default... -footerred: bool # only works when 'boxed'... puts the DEBUG info into footer of a box returns: prints out debug info (unless 'here' option invoked) notes: Enjoy! To test: run: python3 -m doctest -v dbug.py # >>> a = "xyz" # >>> dbug_var(a) DEBUG: [dbug.py; <module>:1] a:xyz '1'

def dbug_demo():

purpose: A quick-n-dirty demo of using dbug()

def ddbug(msg='', *args, ask=False, exit=False):

purpose: this is for use by dbug only... as dbug can't call itself

def display_in_cols(lst, cols=0, reverse='', on='value'):

deprecated as gtable may take it's place input: takes a list or a dict and prints in order across cols options: order default for list is is as-is if it is a dict you can sort "on" default "value" or on "key" , or reverse=True or reverse=False returns: lines (sorted if dict) example: # >>> lst = [*range(1,20)] # >>> display_in_cols(lst) then print lines eg printit(lines)

def do_close(msg='', *args, hchr='=', color='', box_color='', rc=0, **kwargs):

purpose: to provide a boxed closing message default msg is below options: - quote: str # should a random quote from filename provided be included - quoote_box_color: str # box color for quote default="White! on black" - centered: bool # center the output on the screen - shadowed: bool # should the box(es) be shadowed - figlet: bool # use figlet to decorate msg returns: None # dflt_msg = "Enjoy!" input msg or it uses dflt_msg options: 'center' | 'centered' color='red' rc=return code to exit with >>> do_close() ====== Enjoy! ======

def do_edit(file, lnum=0):

purpose: launches vim editor with file a quick-n-dirty utility to edit a file options: - lnum: line number Initiate edit on a file - with lineno if provided

def do_func_demos():

purpose: allows selection of demos within this module - runs the demo function selected options: None return: None

def do_func_docs():

purpose: to get function docs

def do_logo(content='', *args, hchr='-', prnt=True, figlet=False, center=True, shadow=False, **kwargs):

purpose: presents a boxed logo for the begining of a program requires: nothing but you should provide some default content: str|list options: - content: str|list, - prnt: bool, - figlet: bool, - center: bool, - shadow: bool, - box_color: str, - color: str, - fotune: bool <-- requires the fortune app . quote: str <-- requires a filename with quote lines within it - one will be randomly selected if content = "" and /usr/local/etc/logo.nts does not exist then we use "Your Organization Name" if content == "" then open default file: /usr/local/etc/logo.nts if content is a filename then use the lines in that file if content is a str and not a file then use pyfiglet to turn it into ascii letters of print lines

def do_logo_demo():

purpose: demo of using do_logo() returns: None

def do_prcnt_bar(amnt, full_range=100, *args, bar_width=40, show_prcnt=True, **kwargs):

purpose: displays a percentge bar args: amnt (prcnt) options: full_range=100 if you submit this prcnt will be based on it - bar_width=40: int # declares width of bar - color: str # text color - done_color: # color of done portion - undone_color: # color of undone portion - done_chr: str # done character - undone_chr: str # undone character - prompt: str # prompt (before the bar) - suffix: str # suffix (afterr the bar) - brackets=["[", "]"]: list - show_prcnt=True: bool # include the percentage at the end - prnt=False: bool # False to allow use in dashboards # you can tell this to not print so you can include in in a box etc returns: percent bar line as a str #>>> rh = 56 #>>> rl = 50 #>>> cp = 51 #>>> amnt = cp - rl #>>> full_range = rh - rl #>>> print(f"rl {do_prcnt_bar(amnt,full_range)} rh") # rl [██████----------------------------------]16% rh

def docvars(*args, **kvargs):

purpose: wrapper for function to allow variable substitution within its doc I use this in front on a function I call handleOPTS(args) which works with the module docopts Thank you to stackoverflow.com: answered Apr 25 '12 at 1:54 senderle this is a very useful way to allow variables in your __doc__ strings wrap a function with this and use if this way eg: @docvars(os.path.basename(__file__), anotherarg, myarg="abcd") def myfunc(): """ Usage: {0} [-hijk]" Notes: anotherarg: {1} myarg: {myarg} """ return "Done"

def dtree(dir_name='./', *args, **kwargs):

purpose: print a simple directory tree options: - files: bool # default=False - prnt: bool # default=False should we print out the lines - excludes: list | str # default=[] this is a pattern or list of patterns to skip - boxed: bool # boxes all the lines - length: int # default=3 # size of the "fill" returns: list (lines for printing)

def dtree_demo(*args, **kwargs):

purpose: demo of using dtree()" return: None

def escape_ansi(line, *args, **kvargs):

purpose: Removes ansii codes from a string (line) returns: "cleaned no_code" line TODO: allow option to return clr_codes[1], nocode(elem), clr_codes[2] see: split_codes() aka: name should be escape_ansii

def file_exists(file, type='file', *args, **kwargs):

purpose: returns bool if the file (or directory - see options) exists or is it executable options: type: str # Note: type can be "file" or "dir" (if it isn't file the assumption is dir) if type == "x" or "X" then the return bool will depend on if the file is executable returns: bool usage: file_exists('/etc/hosts') True

def find_file_in_dirs(filename, dirs_l=[], prnt=False):

purpose: this is for future use as something like find_file_in_dirs(filename, dirs_l) notes: if dirs_l is empty it defaults to ["./"]

def first_matched_line(filename, pattern, upto=1):

purpose: return: just the first matched line(s) from a filename using pattern required: - filename: str - pattern: str options: - upto: int default=1 # How many matching lines to return returns: matching lines

def fixlol(my_lol=[], *args, **kwargs):

purpose: makes the length or every "row" in a list of lists the same number of elements (length) options: - length: int # defaults to the length of the first row ie len(my_lol[0]) - blank: str|None # defaults to None but can be any string eg blank="..." returns: fixed lol with all rows the same length (number of elements) used by gtable with option "fix"

def flattenit(my_l):

purpose: "flattens nested lists options: none returns: list

def from_to(filename, begin, end, *args, include='none', **kwargs):

purpose: returns lines from a *file* from BEGIN pattern to END pattern" (between BEGIN and END) options: - include: can be equal to "none", top|begin|start, bottom|end, or 'both' -- include='top' will include the begin pattern line, -- include='bottom' will include the end pattern line -- include='both' will include top and end pattern matching lines returns: lines between (or including) begin pattern and end pattern from filename (or a list of lines)

def funcname(n=0):

purpose: returns current function name - primarily used for debugging

def gblock(msgs_l, *args, **kwargs):

purpose: justifies using nclen all strngs in msgs_l and maximizes each string length to the longest string - all lines will be the same length (nclen - no-color len) required: msgs_l: list # list of strings options: - height: int - length | width: int - pad: str # char to use for fill - position=1: str | list | int # eg: 'right center' or 'left top' (default) or [top, left] or 'middle bottom' or 1 (default) or 5 or 9 ... etc left | center | right +-------------------+--------------------+--------------------+ top | 1 | 2 | 3 | | ['top','left'] |['top','center'] | ['top','right'] | ------ +-------------------|--------------------|--------------------+ middle | 4 | 5 | 6 | | ['middle','left'] | [middle','center'] | ['middle','right'] | ------ +-------------------|--------------------|--------------------+ bottom | 7 | 8 | 9 | | ['bottom','left'] | [bottom','center'] | ['bottom','right'] | ------ +-------------------|--------------------|--------------------+ returns: all lines the same length (the length of the max) and with strings justified - a new box with the dimensions given aka: build_box, maxall notes: - this function is designed place a block/box in a position in a larger box or to combine rows and columns into a type of dashboard. - described above is the original design ie: to handle on box (list of strings) - this enhancement if fragile and not fully tested but is great for building dashvboards However: I have modified/enhanced this to allow for building columns and or rows *but* it is difficult to describe how it works Best to give examples - assumes box(x) below is a list of strongs of the same length gblock([box1, box2]) # will build two columns into one block gblock([box1, [box2, box3]]) # will build one row of two columns with the second column having 2 rows (box2 over box3) gblock([[box1], [box2]]) # will build two rows - box1 over box2 gblock([[box1, box2], [box3, box4]]) # will build two columns with the first column holding box1 over box2 while the second column will hold box 3 over box4 option include: - length: int # works just like above - makes the block this length - height: int # " " " - makes the block this height - boxed: bool - title: str - footer: str - txt_center: int # this is important as it will center from the top txt_center number of lines within the created block # typically you would use txt_center=99 to center all the lines within the block

def gblock_demo():

purpose: demo of gblock() returns: None

def gclr(color='normal', text='', **kwargs):

Purpose: to return color code + text (if any) NOTE: sub_color() uses this! input: text: str = "" # if "" then the color code alone is returned color: str = 'normal' # examples: 'red on black', 'bold green on normal', 'bold yellow on red', 'blink red on black' etc reset: bool # adds a color reset after the text Notes: color is the first argument because you may just want to return the color code only run gcolors.demo() to see all color combinations returns: color coded [and text]

def gclr_demo(*args, **kwarg):

purpose: demo of using gclr() returns: None

def gcolumnize(msg_l, *args, **kwargs):

purpose: This will columnize (vertically) a list or a list of blocks or strings input: msg_l: list|lol options: - width|length=0: int # max width or use cols below - cols: int # number of desired columns - sep|sep_chrs|sepchrs=' | ': str # string or character to use between columns - prnt|print|show = False: bool - boxed: bool # box the output - box_color: str # color to use for box border - centered = False: bool # only invoked if prnt == True - title = "": str # only invoked if prnt == True - color: str - footer = "": str # only invoked if prnt == True - positions: list # list of either triplets or lists with 3 values, (row, col, position) --- position can easily be declared as 1-9 -> see gblock().__doc__ return: lines: list # suitable for printit() notes: - handles simple lists or a list of blocks/boxes (a list of lines) - If it is a list of lists (like several boxes made up of lines ) then it will list them next to each other Further is it is a list or rows with a list of boxes for each row then this will try to accomodate eg box1 = +------+ | box1 | +------+ box2 = +------+ | box2 | +------+ boxes = box1 + box2 lines = gcolumnize(boxes) printit(lines) +------+ +------+ | box1 | | box2 | +------+ +------+ or box1 = +------+ | box1 | +------+ box2 = +------+ | box2 | | box2 | +------+ box3 = +----------------+ | box3 box3 box3 | +----------------+ box4 = +------+ | box4 | | box4 | | box4 | | box4 | +------+ row1 = [box1, box2] row2 = [box3, box4] lines = gcolumnize([row1, row2] printit(lines) or mylist = ["One potato", "Two potato", "Three potato", "Four", "Now close the door"] lines = gcolumnize(mylist, width=40) printit(lines) One potato Four Two potato Now close the door Three potato

def gcolumnize_demo():

purpose: A demo of using gcolumnize Great for build quick dashboards

def gcontains(string_s, pattern_m):

purpose: to determine if any pattern (str|list) is a substring of string (string_s) options: none returns: bool

def get_boxchrs(box_style='single', *args, **kwargs):

purpose: given a box_style (ansi, single, solid, double) will return a set of chars for creating a box input: box_style: str return: [tl, hc, ts, tr, vc, ls, rs, ms, bl, bs, br] as a list in the order shown Note: boxed() uses this tl = top_left, hc=horizontal_char, ts=top_separator, tr=top_right, vc=vertical_char, ls=left_separator, rs=right_separator, ms=middle_separator bl=bottom_left, bs=bottom_sep, br=bottom_right

def get_columns(*args, **kwargs):

gets screen/terminal cols OR rows returns int(columns)| int(rows: bool) | int(cols), int(rows) both: bool

def get_dtime_format(s_date):

purpose: returns the format of a date-time stamp string useful for date series in dataframes options: none returns date patters in strftime format

def get_elems(lines, *args, index=False, col_limit=20, **kwargs):

purpose: designed to split a list of lines on delimiter - respects quoted elements that may contain "," even if that is the delimiter - wip - this does the same thing as comma_split but adds a few options TODO Input: lines (as a list) options: - delimiter: str # (default is a comma) - col_limit: bool # max column size default=0 - if 0 no truncation occurs otherwise all elems are limited to col_limit - index: bool # will insert an index (line numbers starting with 0) # not used yet TODO - lst: bool # assumes a single line (ie: lines = str) so it returns a list of elemes from that line instead of a list_of_elems for multiple lines (ie an lol) Returns: an array: list of list (lol - lines of elements aka rows and columns) aka rows_lol

def get_elems_demo(*args, **kwargs):

purpose: demo of get_elems() returns: None

def get_html_tables(url='', *args, **kwargs):

purpose: to pull/scrape all tables off an url required: url requires: import pandas as pd from selenium import webdriver options: - show|prnt: bool # default=False ... whether to print the tables - spinner: bool # default=False ... whether to show a spinner while fetching data returns: list of panda dataframes

def get_html_tst():

purpose: to test get_html() options: start-maximized: Opens Chrome in maximize mode incognito: Opens Chrome in incognito mode headless: Opens Chrome in headless mode disable-extensions: Disables existing extensions on Chrome browser disable-popup-blocking: Disables pop-ups displayed on Chrome browser make-default-browser: Makes Chrome default browser version: Prints chrome browser version disable-infobars: Prevents Chrome from displaying the notification ‘Chrome is being controlled by automated software

def get_mod_docs(mod=__file__, *args, fn='*', **kwargs):

purpose: lists all functions and the docs from a module Note: except some functions eg _demo returns cnt

def get_random_line(file, prnt=False, *args, **kwargs):

purpose: grabs one random line from a file requires: from this_file purify_file, centered, boxed, printit, cat_file import random file: str | list # can be a filename or it can be a list of lines returns: line Note: file has all comments removed first (purified)

def gline(width=0, *args, **kwargs):

purpose: prints a line with msg and options: - width: int, - msg|title: str # default="" msg has to be a key=val pair! eg: gline(60, msg="My Message", just='center') - fc: str # default=" " fill string/character (char(s) used to fill all surrounding space default: lc=rc=fc) - lc: str # default=fc left/edge/corner (char(s) for left corner ie first charater(s)) - rc: str # default=lc right/edge/corner (char(s) for right corner ie last charcter(s)) - pad: str # default="" string/character(s) on each side of msg - lpad: str # default=pad - rpad: str # default=lpad - box_color: str - color: str - lfill_color: str - rfill_color: str - just: str # default = "left"|"l" but can be declared "center"|"c" or 'right'|"r" - prnt: bool # prints the output returns: line: str

def gline_demo(*args, **kwargs):

purpose: demo of using gline() returns: None

def grep_lines(lines, pattern, *args, **kwargs):

purpose: searches lines (or file if lines is a filename) for pattern options: - ic: bool (insensitive case) - rtrn_bool=False: bool # (whether to rtrn lines [default] or bool result) - csv: bool # will convert a list of lists to a list of csv style lines before searching - # and but returns the line as a list, just the way we got it returns: matched line(s) (or True False if rtrn_bool is True) Note: if only one line is matched then it will return that one line otherwise it will return a list of matched_lines

def gselect(selections, *args, **kwargs):

purpose: menu type box for selecting by index, key, or value required: - selections: list or dictionary options: - prompt: str # no need to include ": " - rtrn='' # can be 'k|key' or 'v|val|value' or "i" | "int" <-- tells gselect whether you want it to return a key or a value from a supplied list or dictionary or just user input (default) # if "i"|"int" is invoked then the value of the key will return as an integer (as opposed to a string) This is an important option and allows control over what gets returned. See the Notes below. - show: str # "k|key" or 'v|val|value' <-- tells gselect whether to display a list of keys or a list of values - indx: bool # whether to index (place a number before) each selection shown - quit: bool <-- add "q)uit" to the prompt and will do a sys.exit() if ans in ("q","Q","exit") - multi <-- allows multiple selections and returns them as a list - default|dflt='': # allows you to /declare a default if enter is hit - sep: str # separation chars between cols default=" | " - cols: int # default is 1 column for displaying selections - quit - title - footer - color - box_color - width returns: str | list -- either key(s) or value(s) as a *string* <---IMPORTANT or list (if multiple), your choice Notes: - to understand this function know first that everything is turned into a dictionary first. A list would become a dictionary with the keys being 1,2,3... while the original list would become the keys - this understanding will help with determining the rtrn and show options (key | val) - a dictionary remains as keys and values - with a simple list by default it will return the value in the list - if you want the menu number then use rtrn='k' option!!! examples: > tsts = [{1: "one", 2: "two", 3: "three"},["one", "two", "three"], {"file1": "path/to/file1", "file2": "path/to/file2"} ] > for tst in tsts: ... ans = gselect(tst, rtrn="v") ... ans = gselect(tst, rtrn="k") ----------- To run a function using gselect - write code similar to this: selections = {"Clean up files": 'clean', "Copy file": 'copyfile'} ans = gselect(selections, rtrn="v", quit=True) globals()[ans]() # this will run the function name returned .. eg: clean() or copyfile() obviously you can do a lot with this

def gselect_demo():

demo of using gselect

def gtable(lol, *args, **kwargs):

purpose: returns lines or displays a colorized table from a list_of_lists, df, or dictionary input: rows: str|list|dict|list_of_lists|list_of_dicts|dataframe options: - color: str, - box_style: 'single', 'double', 'solid', - box_color: str, - header|hdr: bool, # header | hdr # highlights the colnames - end_hdr: bool # adds highlighted hdr/colnames to the bottom of the table - colnames: list | str, 'firstrow' | 'firstline' | 'keys' - col_colors: list, # gtable will use this list of colors to set each column, repeats if more cols than colors - neg: bool | list, - nan: str, - alt: bool_val, - alt_color: str, - title: str, - footer: str, - indexes: bool, - box_style: str, - max_col_len|col_limit|col_len...: int, default=100 - human: bool| list, # if bool all numbers will get "humanized", if list syntax = [colname, colname...] and ony those colnames will get "humanized" - rnd: int | dict, # if int all numbers will be rounded to rnd value, if dict syntax is {colname, round_val, colname, round_val} keep in mind if round_val = 0 it will turn that colname into all integers if round > 0 then all the column values will have that many decimal places - sortby: str, - filterby: dict {'field': 'pattern'} # Note: the default is to search the column for matches of rows # where the column "contains" the string/pattern (see regex option) # NOTE: max_col_len WILL affect this pattern search - ci: bool # will make filterby case insensitive default=False - regex|rgx: bool # will force filterby to use exact match to pattern # this option is powerful eg gtable(my_lol, 'regex', filterby={"Symbol": "^Dow 30$|^S&P 500$|^Gold$"},...) - select_cols: list # specify which columns to include - table will be in same order - excluded_cols: list # specify which columns to exclude - write_csv: str, - skip: bool # tells gtable to skip lines of the wrong length - be careful w/this - cell_pad=' ': str # you can set the padding char(s) - strip: bool # strip all white space off of ever element in every row - blanks: str # you can declare how blank cells (blank elements in a row) should appear - fix: bool # default=False - if true then everry row of the data will be made the length of the first row - ignore: bool # default=False builds the table even if the number of columns is different on the rows - makes it easier to troublshoot - cols: int # split a table into several tables or columns (aka chunks) - lol: bool # default=False - will return the conditioned lol (rows of columns) instead of the default printable lines - no_hdr: bool # removes header/colnames row from the table returns lines: list Notes: if colnames="firstrow" then the firstrow will be extracted and used for the header if colnames="keys" and we are passed a dictionary then the colnames will be the dictionary keys I frequenly use this function for financial data analysis or csv files TODO: add head: int and tail: in

def gtable_demo():

purpose: test/demo using gtable() returns: None

def gtitle(width, msg, fc='=', *args, **kwargs):

purpose: quick-n-dirty Title/Separation Line - I use this just to separate sections returns: prints a line with "=" fill character and msg in the middle (centered) with width=width see: gline_demo

def handleCFG(cfg_file='', *args, **kwargs):

purpose: if no cfg_file given it will find the default and return cfg_d (dictionary of dictioanries: cfg.sections; cfg.elem:vals) input: cfg_file: str defaults: cfg_file if it exists is: {myappname.basename}.cfg returns: cfg_d: dict (dictionary of dictionaries - cfg.sections with key, val pairs) use: cfg_d = handleCFG("/my/path/to/myapp.cfg") try: title = cfg_d['menu']['title'] except: title = ""

@docvars(os.path.basename(__file__))
def handleOPTS(args):

Usage: {0} [-hEP] [--dir] [<filename>] {0} -s <func> {0} -S <func> {0} -t [<func>] {0} -T <func> [<fargs>] {0} --version Options -h Help --dir prints all the functions here and exits -t runs all doctest calls -T <func> [<fargs>] runs specified func with optional args=fargs -v, --version Prints version -s <func> Show code block -S <func> Show __doc__

def has_alnum(string):

purpose: test whether a string is all alpha numeric Is a string blank or all white space... isspace() does the samething

def has_substr(text_s, chk_l, *args, **kwargs):

purpose: determin if any sub-string in chk_l is in text_s column_name = "dtime" eg is "time" or "date" in column_name... then use has_substr(column_name, ["time", "date"]) required: - text_s: str - chk_l: list options: - ci: bool # case_insensitive returns True | False used in quick_plot()

def ireplace(s, indices=[], char='|'):

purpose: index replace To get indices use eg: iter = re.finditer(rf"{c}", s) indices = [m.start(0) for m in iter] # next line removes first two and last two indices - just an example indices = indices[2:-2] then use this func with: s: is the string to do the replacements indices: list of indexed positions char: is the char to replace with

def isempty(my_var):

purpose: tests if a variable is empty ie len(my_var) == 0 or my_var is None etc options: None returns: bool

def islod(my_lod, *args, **kwargs):

purpose: is this a list of dictionaries options: None returns: bool

def islol(my_lol, *args, **kwargs):

purpose: determine is my_lol is actually a list of lists required: list - my_lol options: none return: bool True | False

def islols_demo(*args, **kwargs):

purpose: to demonstatrate islol and islos functions required: none optons: none return: none

def islos(my_los=['a', 'list', 'of', 'strings'], *args, **kwargs):

purpose: determines if my_los is a list of strings returns: bool

def isnumber(x, *args, **kwargs):

purpose: determines if x is a number even if it is a percent, or negative, or is 2k or 4b or 10M etc or test for stricktly float options: - float: bool # is this a float - human: test the submission after stripping off "human" symbols like "M" or "G" or "%" etc input: x: str|float|int returns: True|False notes: tests... pos, neg, floats, int, scientific, B(illion), T(trillions), G(ig.*) Kb(ytes|its), Mb(ytes) Can be used on financial data which often includes M(illions) or B(illions) if human option included

def isnumber_demo(*args, **kwargs):

purpose: test/demo of using isnamber() returns: None

def key_swap(orig_key, new_key, d):

purpose: switch or change the keyname (a single key) on an element in a dictionary args: orig_key # original key name new_keyA # new key name d # dictionay to change returns: the altered dictionary

def kv_cols(my_d, cols=3, *args, **kwargs):

input: my_d: dict cols:default=3 <-- both args ie: dict and cols are required! options: - title, header, pad, box_style, box_color: str, color: str, neg: bool, - prnt: bool, footer,title: str, rjust_cols: list, sep,pad: str, max_col_width: int, - centered: bool, box_style: str, human: bool, rnd: bool, box_title: bool (requires title), sep: str - hdr: bool default=True - no_hdr: bool # removes hdr/colnames from tables returns: lines tabalized key-value pairs

def kv_cols_demo():

purpose: demo of using kv_cols() returns: None

def kvarg_val(key, kwargs_d={}, *args, **kwargs):

purpose: returns a value when the key in a key=value pair matches any key given NOTE: key can be a string or a list of strings option: dflt="Whatever default value you want" use: used in function to get a value from a kwargs ky=value pair - eg: def my_function(*args, **kwargs): txt_center = kvarg_val(["text_center", "txt_cntr", "txtcntr"], kwargs, dflt=1) - so if you call my_function(txt_center=99) then txt_center will be set to 99 --- If any key in the list is set = to a value, that value is returned see: bool_val which process both args and kvargs and returns bool_val input key(string), kvargs_d(dictionary of key,vals), default(string; optional) purpose: return a value given by a key=value pair using a matching key (in key list if desired) options: - key provided can be a string or a list of strings - dflt="Whatever default value you want - can be a string, list, int, float... whatever" <-- this is optional, if not declared "" is returned if key in kvargs: return val else: return default returns str(key_val) or default_val(which is "" if none is provided)

def kvarg_val_demo(*args, **kwargs):

WIP

def lineno():

purpose: returns current line number - primarily used for debugging

def list_files(dirs, file_pat='*', *args, **kwargs):

purpose: prints a list of enumerated basename filenames (sorted by name) input: dirs=list|str options: pattern: str|list = "*" # glob pattern return_msgs<bolean> = False prnt<bolean> = False dirs: bool # include dirs dir_only: bool # only dirs links: bool # include links returns: a sorted list of those names or return_msgs and sorted names use: list_files("/tmp")

def long_proc(msg='testing long process', *args, **kwargs):

purpose: this is only for test or demos - it nothing but a sleep

def main(main_args):

purpose: allows user to see some of the fuctionality of this tool set

def matrix(rows, cols, *args, **kwargs):

purpose: initialize a matirx (ie array) required: rows/dim1: int, cols/dim2: int options: - dflt_val=None: anything # default "value" to initialize each "cell" to returns: 2 dim initialized array/matrix aka: init_arr | initarray | init_arr

def max_width_lol(input_table):

purpose: to determin max_width for each "column" in a list of lists this is a way of truncating "columns" returns: column sizes

def maxof(my_l, *args, **kwargs):

purpose: returns length of longest member of a list (after escape_ansii codes are removed) required: list or list_of_lists (lol) options: - length|len|max_len|elem_len: bool # default=True longest length is returned - height|rows|max_height|row_len: bool # default=False largest number of elements in list (typically the number of lines in a list of strings) - elems: bool # default=False in a list of lists this will rerturn the greatest number of elements in each member of a list (see note below) - lst: bool # default=False returns a list which will be the max length(s) or height(s) of each elem in a list returns: int max length of eleemes note: saves me from having to look up how to do this all the time and works with lists or lists of list - sometimes I need to know the number of rows in cols (lol of rows in cols ie: cols_lol = [row1, row2], [row1, row2, row3], [row1, row2]] ... maxof(cols_lol): 3

def maxof_demo():

purpose: Demos of using ruleit() function returns: None

def nclen(line, *args, **kwargs):

purpose: finds the length of a string minus any ansi-codes and returns that lenght returns: length aka: no_color len of line (length w/o ansii codes)

def pp_d(d, between=' ', kv_s=': '):

purpose: pretty print a dictionary deprecated as gtable does this with between (str) placed between elems and kv_s (str) between k and v >>> d = {"one": 1, "two": 2, "three": 3} >>> print(pp_d(d)) one: 1 two: 2 three: 3

def printit(msg, *args, **kwargs):

purpose: prepares and prints (option) msg: str|list and can put in unicode color box, centered in terminal and with color required: msg: str|list (can contain color codes (see below) options: "boxed" | boxed=False # prepares a box around msg "centered" | centered=False # centers horizontally msg on a termial screen "shadowed" | shadowed=True # adds a shadow typically around a box "prnt" | prnt=True # print line(s) or just return them as a str (useful for input(printit("What do you want? ", 'centered', prnt=False, rtrn_type="str"))) txt_center: int # tells how many lines from the top to center within a list box_color: str # eg "blink red on black" color: str # eg "bold yellow on rgb(40,40,40)" title: str # puts a title at top of a box footer: str # puts a footer at the bottom of a box style: str # to select box style - not fully functional yet shift: int # how far to the left (neg) or to right (pos) to shift a centered msg width: int # forces msg to fit in this width using text wrap rtrn_type: "list" | "str" # default is list function is pretty extensive... color coding: activates decoding using color tag(s) eg msg = "my message[blink red on black]whatever goes here[/]. The end or close tag will reset color") returns: msgs # list [default] or str depending on rtrn_type

def printit_demo(*args, **kwargs):

purpose: demo of using printit() returns: None

def progress(progress, *args, **kwargs):

purpose: displays a progress bar typically used within a loop options: - width - prompt - color - done_color - undone_color - prnt - COLOR - DONE_COLOR - UNDONE_COLOR - RESET - done_chr - undone_chr - status - center_b - shift: returns: none # prcnt = 0.20 # progress(prcnt, width=60) Percent: [############------------------------------------------------] 20% # or >>> for i in range(100): ... time.sleep(0.1) ... progress(i/100.0, width=60) Percent: [############################################################] 99%

def purify(content, *args, **kwargs):

purpose: de-comments a file, aka removes all comments denoted by "#" ... input: file: str return lines: list (decommented lines)

def pyscraper(url, pat):

I may deprecate this as I rarely use it example: pat # pat = '<span class="Trsdu\(0.3s\) Fw\(b\) Fz\(36px\) Mb\(-4px\) D\(ib\)" data-reactid=".*?".*?>.*?</span.*?>' # noqa: Be careful... pay attention to the html page when using a script ... many sites detect the script and block real output Required: from urllib.request import urlopen import re

def quick_plot(data, *args, **kwargs):

purpose: quick display of data in a file or in dataframe displays a plot on a web browser if requested required: data: df | str | list (filename: csv or dat filename) options: - show | prnt: bool - centered: bool - title: str - footer: str - tail: int # for the last n rows of the df default=35 - choose: bool # invokes gselect multi mode to allo"w selections of columns to display in the plot (graph) - selections: list # you can declare what columns to plot - web: bool # displays to your browser instead of a plot figure - dat: bool | str # I sometimes use a commented firstline for headers - # using 'dat' declares this to be true, if character is used ie dat=":" # then that will be used as the delimiter - type: str # default=line, bar, barh, hist, box, kde, density, area, pie, scatter, hexbin - colnames: list | str # default = [] if it is a str="firstrow" then the firstrow obviously will be treated as colnames - mavgs: bool # 50 day and 200 day moving averages added to plot - box_text: str | list # string or lines to add to a box in fuger default="" - subplot: str # sub plot with area under filled using column name = subplot - save_file: str # name of file to save the plot figure to. default="" - delimiter: str # assumes a filename for data (above) and use delimiter to seperate elements in each line of the file - hlines: dict # dictionary eg: {"target": 44, "strike": 33, ...} can be one or several - plines: bool # pullback_lines - only useful for stock history charts - rnd: int # round numbers to int - only useful if show or prnt is invoked for gtable display (see option show | prnt) # returns: df returns: lol # list of rows each of which is a list of columns NOTE: if a filename is used as data it will get "purified" by removing all comments first (except the first line of a dat file.) tail, title and footer only affect the gtable if show is True

def quick_plot_demo():

purpose: to provide examples of displaying data in plots returns: None

def reduce_line(line, max_len, pad):

purpose: reduce a line to no more than max_len with and no broken words then return the reduced_line, and remaining_line returns: tuple - this_line(reduced) and the remaining part of the line Note - used in wrapit() ?

def regex_col(file_lines, pat='', col=7, sep=''):

regex for a patern in a word|column file_lines can be a filename or lines (list) col starts at 0 to be consistent with coding standards returns lines where pat matches col number word ie words[col]

def remap_keys(my_d, remap_d, *args, **kwargs):

purpose: remaps keys names AND can select only the k.v pairs you want (in the order specified) (ie option: 'mapped_only') options: - mapped_only: bool, - rnd: int # rounds out numbers to rnd scale returns: my_d (remapped and optionally selected pairs) notes: remap_d should be dict {orig_key: new_key, ...} but can be a list only (assumes and sets mapped_only=True) This is a very useful function that allows you to pick/select columns from a given dictionary in your order and rename any keys as well I use this a lot when I download financial data from a web api created: 20220423 gwm

def replace_all(msg, with_d):

purpose: replaces every dict key with dict value in a string with_d eg: {' ', ' ', 'foo', 'bar'} returns: str TODO need more doc info here

def retry(howmany, *exception_types, **kwargs):

purpose: a wrapper to retry a function x (howmany) times notes: there is a module called retrying that deserves more research and it provides a wrapper function called @retry() useage: eg: @retry(5, MySQLdb.Error, timeout=0.5) def the_db_func(): # [...] pass This is untested - completely expimental It is essentially the same as: for attempts in range(3): try: do_work() break except Exception as e: print(f"Attempts: {attempts}. We broke with error: {e}")

def rgb(r=80, g=80, b=140, text='', fg=False, bg=False, prfx=False, reset=False):

purpose: translated rgb(r,g,b) text into ansi color CODE input: r, g, b, text prfx: bool = False bg: bool = False # if set to true the color is applied to bg returns: rgb color coded text

def rootname(filename, *args, **kwargs):

purpose: returns the root name of a full filename (not path, no extension) input: filename: str returns: ROOT_NAME: str

def rowscols_cols(lol, cols, *args, **kwargs):

purpose: this takes a longish lol - namely, rows of columns and allows you to split those rows into X columns. This is most likely used to split up rows of columns for gtables so an option include colnames to add to the top of each new column of rows cols: This is an experiment but I think it could be useful Here is a simple visual row_of_cols +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ | | | | +------+-----+----+ split_tables = rowscols_cols(row_of_cols, 2) +------+-----+----+ +------+-----+----+ | | | | | | | | +------+-----+----+ +------+-----+----+ | | | | | | | | +------+-----+----+ +------+-----+----+ | | | | | | | | +------+-----+----+ +------+-----+----+ | | | | +------+-----+----+ TODO? - having seconds thoughts that this should be part of gtables...

def ruleit(*args, **kwargs):

purpose: This is for development purposes It draws a rule across the screen and that is all it does It fails to prepare your meals or schedule your week's agenda, sorry. options: - width: int # default=0 - truncates at this len otherwise it is screen length - cntr: bool # default=False - provide center info - prnt: bool # default=True - whether to print returns: printed ruler line with tick marks and marker numbers below

def ruleit_demo(*args, **kwargs):

purpose: demo of using ruleit() returns: None

def run_cmd(cmd, *args, prnt=False, runas='', **kwargs):

purpose: runs cmd and returns output eg: out = run_cmd("uname -o",False) # now you can print the output from the cmd: print(f"out:{out}") options: - lst: bool # ouput will return as a list of line rather than a str - rc: bool # returns the cmd return code instead of output - both: bool # returns (output, rc) - runas: str # you can declare who to run the cmd as - prnt: bool # print output - returns None returns: output from command Note: if runas == sudo then the command will be sun with sudo... - this function strips out all ansi code and filters all errors - does not currently return error msgs - as it is today 20221201 you lose color output - use os.system(cmd) instead for simple output or use 'prnt' option Test: >>> r = run_cmd("uname -o") >>> print(r) GNU/Linux <BLANKLINE>

def run_cmd_demo():

purpose: demo of run_cmd(cmd) returns: None

def run_cmd_threaded(cmd, *args, **kwargs):

purpose: runs a cmd as a thread options: - lst: bool # returned output lines will be put into a list rather than a str return: output from cmd Note: Please, be aware that a result will be returned only after this finishes so put it "later" rather than "sooner" in your app - does not currently return error msgs

def sayit(msg, *args, prnt=True, **kwargs):

purpose: This will use computer voice (espeak) to "say" the msg options - prnt: will print as well # this is very limited - gender: str # m | f - volume: float # 0 - 1 - rate: int # default = 150 - tone: int # 1 - 5 <-- this does not seem to do anything??? returns: None notes: # use espeak --voices to see them all then add +m|f1-? # genders = ["m", "f"] # tonals = ["1", "2", "3", "4", "5"] # for gender in genders: # for tone in tonals: # voice = f"'english-us+{gender}{tone}'" # engine.setProperty('voice', voice) # msg = f"The time is {date.today().strftime('%B %d %Y')}. My voice is {voice}" # print(msg) # engine.say(msg)

def sayit_demo(*args, **kwargs):

purpose: demo of using sayit() returns: None

def select_file(path='./', *args, pattern='*', prnt=True, color='', boxed=False, box_color='', title='', footer='', shadow=False, center=False, displaywidth=0, rtrn='value', **kwargs):

purpose: select a file (or dir) from using pattern(s) required: options: - path: str|list (defaults to "./") - pattern: str|list - prompt: str - mtime: bool # include mtime in listing - centered - dirs: bool # include dirs - dirs_only: bool # only directories - prnt: bool - shadow - footer - width=0 use: f = select_file("/home/user","*.txt") prints a file list and then asks for a choice returns basename of the filename selected Note: this uses list_files

def shades(color, num=16):

purpose: returns a list of increasing intensity color shades requires = color: str options: - num=16 <-- number to divide into 255 ~ the number of color intensities - rtrn??? TODO return codes or text... CODES | strings/text/txt returns list # of ncreasing colors

def shadowed(lines=[], style=4, color='grey'):

purpose: adds shadowing typically to a box requires: input: lines as a list output: lines as a list Use this to see all the styles: msg = "this is my message" for n in range(0,5): printit(centered(shadowed(boxed(msg + f" style: {n}"),style=n)))

def sorted_add(filename, line, after='', before=''):

purpose: to insert a line between two patterns in a sorted way insert line into filename between after and before patterns the patterns need to be regex ie: r"pattern" assumes the block from after to before is sorted returns: new_lines eg: line = 'Insert this line (alphabetically) after "^-alt" but before "^-[a-zA-Z0-9] within block' filename = "/home/geoffm/t.f" after = r"^-alt" before = r"^-[a-zA-Z0-9]" lines = sorted_add(filename, line, after, before) printit(lines)

def Spinner_demo():

purpose: demo of Spinner

def split_codes(val, *args, **kwargs):

purpose: to split out ansi codes and return them input: elem: str (that contains ansi codes for color) options: TODO include elem dflt=False returns: codes: list (unless elem=True [or 'with_elem' or 'asdict'], then it is a dictionary with preffix, elem, and suffix as key/value pairs) notes: - used in cond_num() aka: color_neg() - NOTE: this function expects both a prefix code and a suffix code! - this function is not perfect and can lead to problems so use judiciously

def split_codes_demo(my_s=(gclr('red')+'test string')+gclr('reset'), *args, **kwargs):

purpose: test/demo of splitting ansii code away from a string returns: None

def splitit(s, delimiter=' '):

purpose: given a string (s), split it using delimiter which can be a string or regex requires: import re input: - s: str # string to split - delimiiter=" ": str options: none returns: phrases: list # string split into elements notes: eg: delimiter = r"["|'] +[-–—―] +" # amazingly all those dashes are different symbols... phrase = splitit('"A great city is not to be confounded with a populous one" - Aristotle', )

def sub_color(clr, *args, **kwargs):

purpose: substiture ansi color CODE for given color returns ansi-CODE

def transcript_demo():

Undocumented

def transcript_start(filename, *args, **kwargs):

Start class Transcript(object=filename), appending print output to given filename

def transcript_stop(*args, **kwargs):

Stop class Transcript() and return print functionality to normal

def try_it(func, *args, attempts=1, **kwargs):

BROKEN BROKEN BROKEN This is a wrapper function for running any function that might fail - this will report the error and move on use: @try_it def my_func(): print("if this failed an error would be reported ") my_func()

def try_to_get(driver, pat='', by_type='link', action='none'):

may deprecate this as I rarely use it This is for use with selenium requires: from selenium import webdriver from selenium.webdriver.common.keys import Keys from selenium.webdriver.common.by import By from selenium.webdriver.support.ui import WebDriverWait from selenium.webdriver.support import expected_conditions as EC

def tst(*args, **kwargs):

purpose: for development one testing only - subject to change at anytime returns: None notes: This is for testing only This is just an example testing function. This example shows how you can quickly test whatever you want (any function) while you are still editing a file. You can completely remove this function. or rename it or call another function within it or leave it as an example. It demonstrates the use of the -T argument. This is a test function and can be called while editing in vim with... :! ./% -T tst all,my,arguments,go=here or :! ./% -T tst This is farg1 or :! ./% -T tst This is farg1 farg2 or :! ./% -T tst This is farg1 farg2,my_kwarg=this_val or :! ./% -T tst This is farg1 "farg2, my_kwarg=this val" or :! ./% -T tst This is farg1 "farg2,my_kwarg=this val" Notes: The args here are do not need to be separated by a space and there is no need to use any quotes unless your key value needs a space. All variables will get quoted for you. If you separate your function arguments with a space then you will need to quote all the arguments as one string The there is a space(s) anywhere in the arguments just quote the while set of argument words

def usr_input(prompt='Your input: ', *args, **kwargs):

purpose: allow user input with editing options:: - prompt: str = "Your input: " - edit: bool - dft: str - centered: bool - shift: int - update: dict - length: int = 0 # all lines will display with the same length returns: edit or input data as str or dict if update option Notes: - this function is typically called by usr_update() - see usr_update()

def usr_input_demo(*args, **kwargs):

purpose: demo of usr_input() returns: None

def usr_update(my_d, *args, **kwargs):

purpose: given a dict, and a list of keys to change - allow user update(s) to values in my_d dictionary go through the list of keys to fix and prompt user for new value, present the current value as default args: my_d: dict # dict to have updated options: - fix: list # default=[] - list of keys to prompt user for change; if empty, use all the my_d keys - centered: bool # default=False - whether to center everything on the screen - edit: bool # defualt=False - whether to allow text edit in place or the default of input replacement input - no_edits: list # default=[] - list of keys that are presented but not editable - quit: bool # default=False - whether to immediately quit on an entry of "q" or "Q", or "quit" returns: my_d (with user updates) Notes: - what is in the passed dict values is what will be presented as the default. - aka: user_edit() - normally usr_update() calls this function - this function calls usr_input(), ie: it superceded usr_input

def usr_update_demo(*args, **kwargs):

purpose: demo for usr_update() return: None

def wrapit(sentence, length=20, *args, **kwargs):

purpose: turns line(s) into a list of strings with full words less than or equal to length input is sentence which can be a string or list returns lines list wrapped using length and color if provided NOTE: all color codes will get stripped out before processing requires import of wrapper

def wrapit_demo(*args, **kwargs):

purpose: demo of using wrapit returns: None

def write_file(data, fname, *args, **kwargs):

purpose: writes data to a file typically as a csv file (or a .dat file) - creates a new file or appends an existing file options: - colnames: list (adds hdr line if not currently there) - comment_lines: str | list - bak: bool # make a backup file - indx: bool # not used yet - future flag for adding an index col (first column) or not - prnt: bool # turns on print - ask: bool # ask before actually writing data to file (before overwriting the file) - append: bool # whether to append data - the default=False whereby submitted data will overwrite the file - dat: bool # this is a special flag to declare that the first line (hdr) is made a comment starting it with "#" returns: bool # true if successful write Notes: - only use this to write a data file = either csv (or a dat file which is a csv file with the header commented) - data should be a list of lists (rows of cols) - assumes first line is comma delimited colnames or use colnames option (in a dat file the first line will be commented) - all comments will go to/near the top - if the file ends with the ".dat" extension it will be treated as a 'dat' file

def xlate_clr(color):

purpose: translates special color names to rgb(r,g,b) for processing requires: special color eg: - greyXX | grayXX # where XX is a precent gradient of gray from 0,0,0 for black! to 255,255,255 white - white! # solid 255,255,255 white - black! # solid 0,0,0 black - red! # solid bright 255,0,0 red - green! # solid bright 0,255,0 green - blue! # solid bright 0,0,255 blue - blue! # solid bright 0,0,255 blue - blue! # solid bright 0,0,255 blue - yellow! # solid bright 255,255,0 yellow - magenta! # solid bright 255,0,255 magenta - cyan! # solid bright 0,255,255 cyan returns: rgb(r,g,b) text string instead of supplied color

BLACK =

Undocumented

Value
    gclr('rgb(0,0,0)')

RESET =

Undocumented

Value
    gclr('reset')

SCRIPT =

Undocumented

Value
    os.path.basename(__file__)

__version__: `str` =

Undocumented

bg_colors_d: `dict[str, str]` =

Undocumented

dtime =

Undocumented

fg_colors_d: `dict[str, str]` =

Undocumented

styles_d: `dict` =

Undocumented