1

"""

     2

    Tree-based URL mapping.

     3

     4

    urltree is used to construct a tree-like structure of URL handlers, and to match a given URL against the tree,

     5

    returning the matching handler.

     6

     7

    URLs are handled as a sequence of labels, separated by slashes (/). Thus, an URL like /foo/bar/baz would be handled

     8

    as a list of three labels:

     9

        ['foo', 'bar', 'baz']

    10

    11

    The URL handler rules are constructed as a sequence of Labels, which then match and evaluate URL segments.

    12

    13

        StaticLabel just matches a pre-defined/constant segment, and is used to route URLs through the URL tree. 

    14

    15

        ValueLabel matches segments dynamically, capturing them as a typed value. It also supports default values.

    16

    17

    urltree also handles building URL strings for a given handler, and a set of values.

    18

    19

    urltree can also handle query-string parameters (i.e. GET params).

    20

    21

"""

    22

    23

import re

    24

import os.path

    25

    26

import werkzeug

    27

    28

class URLError (Exception) :

    29

    """

    30

        Error with an URL definition, parsing, or value handling.

    31

    """

    32

    33

    pass

    34

    35

class URLRuleError (URLError) :

    36

    """

    37

        Error in URLTree structure definition.

    38

    """

    39

    40

class URLMatchError (URLError) :

    41

    """

    42

        Error looking up the URL against our URLTree.

    43

    """

    44

    45

class URLValueError (URLError) :

    46

    """

    47

        Error parsing an URL segment's value via URLType.

    48

    """

    49

    50

    pass

    51

    52

class URLBuildError (URLError) :

    53

    """

    54

        Error re-constructing an outgoing URL.

    55

    """

    56

    57

class Label (object) :

    58

    """

    59

        Abstract base class for URL segment-matching rules.

    60

    61

        A Label subclass is constructed by parse()ing a text-form URL segment spec (== label), and knows how to do a

    62

        yes/value/no match() against an URL segment, as well as re-build() the URL segment for the matched value.

    63

    64

        XXX: rename to URLRuleLabel or something like that

    65

    """

    66

    67

    @staticmethod

    68

    def parse (spec, defaults, config) :

    69

        """

    70

            Parse the given label-spec, and return an appropriate Label subclass instance.

    71

    72

                spec            - the rule specification as text

    73

                defaults        - externally supplied { key: default } dict of default values

    74

                config          - URLConfig instance to use for constructed Label

    75

        """

    76

    77

        # empty/root?

    78

        if not spec :

    79

            return EmptyLabel()

    80

    81

        # construct subclass instance by matching against regexps

    82

        for label_type in (

    83

            ValueLabel,

    84

            StaticLabel,

    85

        ) :

    86

            # test

    87

            match = label_type.PARSE_RE.match(spec)

    88

    89

            if match :

    90

                return label_type.parse(match, defaults, config)

    91

    92

        # invalid

    93

        raise URLError("Unrecognized label: %r" % (spec, ))

    94

    95

    def match (self, value=None) :

    96

        """

    97

            Match this label against the given URL segment, returning one of :

    98

    99

                * True to match without a value

   100

                * False/None to not match, and continue looking

   101

                * a (key, value, label, is_default) capture-tuple to capture a named value from the URL segment

   102

   103

                value       - a segment from the URL as text, or None to force default value

   104

        """

   105

   106

        raise NotImplemented()

   107

   108

    def build (self, values) :

   109

        """

   110

            Re-construct this label, using values from the supplied { key: value } dict if needed.

   111

        """

   112

   113

        raise NotImplemented()

   114

   115

    def build_default (self, values) :

   116

        """

   117

            Return an (is_default, value) tuple

   118

   119

            XXX: used internally by build()?

   120

        """

   121

   122

        raise NotImplemented()

   123

   124

   125

class EmptyLabel (Label) :

   126

    """

   127

        An empty label, which matches empty URL segments, i.e. '//foo' or '/'

   128

    """

   129

   130

    def __eq__ (self, other) :

   131

        """

   132

            Just compares type

   133

        """

   134

   135

        return isinstance(other, EmptyLabel)

   136

   137

    def match (self, value=None) :

   138

        """

   139

            Matches empty segment.

   140

        """

   141

   142

        # no default

   143

        if value is None :

   144

            return False

   145

   146

        # only empty segments

   147

        if value == '' :

   148

            return True

   149

   150

        return False

   151

   152

    def build (self, values) :

   153

        return ''

   154

   155

    def build_default (self, values) :

   156

        return (False, '')

   157

   158

    def __str__ (self) :

   159

        return ''

   160

   161

class StaticLabel (Label) :

   162

    """

   163

        A simple literal Label, used to match fixed segments in the URL.

   164

    """

   165

   166

    PARSE_RE = re.compile(r'^(?P<name>[a-zA-Z0-9_.-]+)$')

   167

   168

    @classmethod

   169

    def parse (cls, match, defaults, config) :

   170

        """

   171

            Construct and return a new instance from the given PARSE_RE match

   172

        """

   173

   174

        # use name as required segment value

   175

        return cls(match.group('name'))

   176

   177

    def __init__ (self, name) :

   178

        """

   179

            The given name is the literal name of this label

   180

        """

   181

   182

        self.name = name

   183

   184

    def __eq__ (self, other) :

   185

        """

   186

            Compares names

   187

        """

   188

   189

        return isinstance(other, StaticLabel) and self.name == other.name

   190

   191

    def match (self, value=None) :

   192

        """

   193

            Match exactly -> True

   194

        """

   195

   196

        # no defaults

   197

        if value is None :

   198

            return False

   199

   200

        # match name

   201

        elif value == self.name :

   202

            return True

   203

   204

        # fail

   205

        else :

   206

            return False

   207

   208

   209

    def build (self, values) :

   210

        return self.name

   211

   212

    def build_default (self, values) :

   213

        return (False, self.name)

   214

   215

    def __str__ (self) :

   216

        return self.name

   217

   218

class ValueLabel (Label) :

   219

    """

   220

        A label with a key and a typed value

   221

    """

   222

   223

    # / "{" <key> [ ":" <type> ] [ "=" [ <default> ] ] "}" /

   224

    PARSE_RE = re.compile(r'^\{(?P<key>[a-zA-Z_][a-zA-Z0-9_]*)(:(?P<type>[a-zA-Z_][a-zA-Z0-9_]*))?(=(?P<default>[^}]*))?\}$')

   225

   226

    @classmethod

   227

    def parse (cls, match, defaults, config) :

   228

        """

   229

            Construct and return a new instance from the given PARSE_RE match

   230

        """

   231

   232

        # value name

   233

        key = match.group('key')

   234

   235

        # value type, or None

   236

        type_name = match.group("type")

   237

   238

        # lookup URLType, None -> default type

   239

        type = config.get_type(type_name)

   240

   241

        # get default value from dict, or None

   242

        default = defaults.get(key)

   243

   244

        if not default :

   245

            # default vlaue from expr?

   246

            default = match.group('default')

   247

   248

            if default :

   249

                # parse text-form default to actual value

   250

                # XXX: is this "" or None if match is for '{foo=}' ?

   251

                default = type.parse(default)

   252

   253

        # build

   254

        return cls(key, type, default, type_name)

   255

   256

   257

    def __init__ (self, key, type, default, type_name) :

   258

        """

   259

            The given key is the name of this label's value.

   260

   261

            The given type_name is is None for the default type, otherwise the type's name. Type is a URLType.

   262

   263

   264

                key         - the name of this label's value

   265

                type        - the URLType used to parse/build the value

   266

                default     - default for value, if no value is given in URL, or None for no default (value required)

   267

                type_name   - parsed name for the type; used for debugging

   268

        """

   269

   270

        # store

   271

        self.key = key

   272

        self.default = default

   273

   274

        # type

   275

        self.type_name = type_name

   276

        self.type = type

   277

   278

    def __eq__ (self, other) :

   279

        """

   280

            Compares keys

   281

        """

   282

   283

        return isinstance(other, ValueLabel) and self.key == other.key

   284

   285

    def match (self, seg=None) :

   286

        """

   287

            Match segment -> (key, value, type, is_default)

   288

        """

   289

   290

        if seg is None and self.default is not None :

   291

            # default value

   292

            return self.key, self.default, self.type, True

   293

   294

        # we don't have a default value, so don't match partial URLs

   295

        elif not seg :

   296

            return False

   297

   298

        # test against type's syntax

   299

        elif not self.type.test(seg) :

   300

            return False

   301

   302

        else :

   303

            # convert with type

   304

            value = self.type.parse(seg)

   305

   306

            # False == non-default value

   307

            return self.key, value, self.type, False

   308

   309

    def build (self, values) :

   310

        """

   311

            Return either the assigned value from values, our default value, or raise an error

   312

        """

   313

   314

        # just proxy to build_default

   315

        return self.build_default(values)[1]

   316

   317

    def build_default (self, values) :

   318

        """

   319

            Check if we have a value in values, and return based on that.

   320

        """

   321

   322

        # state

   323

        is_default = False

   324

   325

        # value given?

   326

        if self.key not in values or values[self.key] is None :

   327

            if self.default is None :

   328

                # no value given for required label

   329

                raise URLBuildError("No value given for label %r" % (self.key, ))

   330

   331

            # use default

   332

            else :

   333

                is_default = True

   334

                value = self.default

   335

   336

        else :

   337

            # lookup the value to use

   338

            value = values[self.key]

   339

   340

            # smart-match against default value

   341

            # XXX: would it be better not to omit it as a default value in this case?

   342

            is_default = bool(value == self.default)

   343

   344

        # convert value to str

   345

        value = self.type.build(value)

   346

   347

        # return

   348

        return (is_default, value)

   349

   350

    def __str__ (self) :

   351

        """

   352

            Pretty-format back into parsed form.

   353

        """

   354

   355

        return '{%s%s%s}' % (

   356

            self.key, 

   357

            (':%s' % (self.type_name, ) if self.type_name is not None else ''),

   358

            '=%s' % (self.default, ) if self.default is not None else '',

   359

        )

   360

   361

class QueryItem (object) :

   362

    """

   363

        Like a normal URL Label, except for dealing with query-string arguments.

   364

    """

   365

   366

    @classmethod

   367

    def parse (cls, spec, defaults, config) :

   368

        """

   369

            Construct and return a new instance from the given spec

   370

        """

   371

   372

        # parse default value

   373

        if '=' in spec :

   374

            # default value, might be empty

   375

            spec, default_spec = spec.split('=')

   376

   377

        else :

   378

            # no default, value required

   379

            default_spec = None

   380

   381

        # parse type

   382

        if ':' in spec :

   383

            # use named type

   384

            spec, type_name = spec.split(':')

   385

        else :

   386

            # use default type

   387

            type_name = None

   388

   389

        # name for value

   390

        key = spec

   391

   392

        # URLType

   393

        type = config.get_type(type_name)

   394

   395

        if key in defaults :

   396

            # default value from external defaults dict

   397

            default = defaults[key]

   398

   399

        elif default_spec :

   400

            # given default value spec

   401

            default = type.parse(default_spec)

   402

   403

        elif default_spec is not None :

   404

            # XXX: no default value, but not required either... silly

   405

            default = ''

   406

   407

        else :

   408

            # no default value, required

   409

            default = None

   410

   411

        # build

   412

        return cls(key, type, default)

   413

   414

    def __init__ (self, key, type, default) :

   415

        """

   416

            The given key is the name of this label's value.

   417

   418

            The given type_name is is None for the default type, otherwise the type's name. Type is a URLType.

   419

   420

   421

                key         - the name of this label's value

   422

                type        - the URLType used to parse/build the value

   423

                default     - default for value, if no value is given in URL, or None for no default (value required)

   424

        """

   425

   426

        # store

   427

        self.key = key

   428

        self.type = type

   429

        self.default = default

   430

   431

    def match (self, arg=None) :

   432

        """

   433

            Parse value from given query-string argument for this key

   434

   435

                arg         - the list of query-string values given, or None for missing value.

   436

   437

            Returns value to use, or None to omit.

   438

        """

   439

   440

        if not arg :

   441

            if self.default is None :

   442

                # no default value!

   443

                raise URLValueError("No value given for query string param: ?%s=..." % (self.key, ))

   444

   445

            elif self.default == '' :

   446

                # XXX: omit

   447

                return None

   448

   449

            else :

   450

                # use default value

   451

                return self.default

   452

   453

        # parse with our type

   454

        value = None

   455

   456

        for value_spec in arg :

   457

            if value is None :

   458

                # parse first

   459

                value = self.type.parse(value_spec)

   460

   461

            else :

   462

                # parse multiple

   463

                value = self.type.append(value, self.type.parse(value_spec))

   464

   465

        # ok

   466

        return value

   467

   468

    def build (self, values) :

   469

        """

   470

            Build and return list of query-string values to pass for this argument, or None to omit.

   471

        """

   472

   473

        if self.key not in values :

   474

            if self.default is None :

   475

                # fail

   476

                raise URLBuildError("No value given for query string arugment %r" % (self.key, ))

   477

   478

            else :

   479

                # omit, and use default value

   480

                return None

   481

   482

        else :

   483

            # lookup our value

   484

            value = values[self.key]

   485

   486

            if value is not None :

   487

                # map to values

   488

                return self.type.build_multi(value)

   489

   490

            else :

   491

                # omit

   492

                return None

   493

   494

   495

class URLType (object) :

   496

    """

   497

        Handles the type-ness of values in the URL

   498

    """

   499

   500

    def test (self, value) :

   501

        """

   502

            Tests if the given value is accepted for this type.

   503