Package: digitmap
digitmapPackage for working with digit maps - a syntax for indicating the sequence of digits that define
a valid and complete dialing attempt by a VoIP telephone user.FeaturesParses digit maps into their individual string patternsConstructs digit maps from component objectsProcesses strings of dial events for matches to a digit map (full and partial)InstallationpipinstalldigitmapWhat are digit maps?Naturally, VoIP systems must collect digits dialed by a telephone user in order to route their call. Most call agents (i.e. IP phones) support two modes of dialing: on-hook and off-hook dialing. On-hook dialing is when the user dials the desired phone number while the handset is still 'on-hook', and the phone device sends the digits dialed to the gateway when the user lifts the handset.Determining what number was dialed is simple, since the phone interprets lifting the handset as the user completing their dial. However, off-hook dialing - where the user lifts the handset first then dials the digits - is more difficult to handle. Without a discreet action for the user to signal they have finished dialing, deciding what number has been dialed is not as straight-forward.The digit map is a mechanism that was proposed inRFC 3435to help address this problem. Based on the Unix egrep syntax, a digit map is defined using a series of patterns that describe the valid sequences of digits that when transmitted from via the gateway, will result in a successful routing.Overview of digit map syntaxFor example, the dial plan for a VoIP system might be defined as follows:Dial...for...0Local operator00Long distance operatorany 4 digitsLocal extensions8 + any 7 digitsLocal numbers# + any 7 digitsShortcut to local numbers at other corporate sites* + any 2 digitsStar services9 + 1 + any 10 digitsLong distance numbers9 + 011 + up to 15 digitsInternational numbersThe corresponding digit map for this dial plan would be:(0T|00T|[1-7]xxx|8xxxxxxx|#xxxxxxx|*xx|91xxxxxxxxxx|9011x.T)Digit maps can contain one or more individual strings that each describe one of these such rules. The following elements can be used in defining digit maps, each with their own meaning:ElementDescription0-9,A-D,#,*A single DTMF digit or symbolxAny DTMF digit (0-9)[1-4]Any DTMF digit in the specified range(s). In this example, digits1,2,3, and4would be matched. Multiple digits and ranges can be placed between the brackets..Zero or more occurrences of the preceeding elementTTimer event from the call agent. This symbol is typically used to indicate that the call agent has timed out waiting for additional digits.UsageParsing a digit mapimportdigitmapasdm# match any 7-digit number OR any 3-digit number ending in '11`expr="(xxxxxxx|x11)"digit_map=dm.parse(expr)print(repr(digit_map))Output:DigitMap([
    DigitMapString([
        WildcardElement(),
        WildcardElement(),
        WildcardElement(),
        WildcardElement(),
        WildcardElement(),
        WildcardElement(),
        WildcardElement()
    ]),
    DigitMapString([
        WildcardElement(),
        DtmfElement("1"),
        DtmfElement("1")
    ])
])Constructing a digit mapimportdigitmapasdmimportdigitmap.modelasdm_model# match any 7-digit number OR any 3-digit number ending in '11`digit_map=dm_model.DigitMap([dm_model.DigitMapString([dm_model.WildcardElement(),dm_model.WildcardElement(),dm_model.WildcardElement(),dm_model.WildcardElement(),dm_model.WildcardElement(),dm_model.WildcardElement(),dm_model.WildcardElement()]),dm_model.DigitMapString([dm_model.WildcardElement(),dm_model.DtmfElement("1"),dm_model.DtmfElement("1")])])print(str(digit_map))Output:(xxxxxxx|x11)Processing a string of dial events for matchesfromdigitmapimportmatch# match any 7-digit number OR any 3-digit number ending in '11`expr="(xxxxxxx|x11)"dial_str="411"result=match(expr,dial_str)print(f"Full matches:{result.full_matches}")print(f"Partial matches:{result.exact_matches}")*Output:Full matches: ['x11']
Partial matches: ['xxxxxxx']SupportPlease use the project'sIssues pageto report any issues.ContributingInstalling for developmentpoetryinstallLinting source filespoetryrunpylint--rcfile.pylintrcsrc/digitmapRunning testspoetryrunpytestLicenseThis library is licensed under the terms of theMITlicense.