1

"""

     2

    Tree-based URL mapping

     3

"""

     4

     5

import re

     6

import os.path

     7

     8

# for Mapper

     9

from lib import map

    10

    11

class URLError (Exception) :

    12

    """

    13

        Error with an URL definition

    14

    """

    15

    16

    pass

    17

    18

class LabelValue (object) :

    19

    """

    20

        Represents the value of a ValueLabel... love these names

    21

    """

    22

    23

    def __init__ (self, label, value) :

    24

        """

    25

            Just store

    26

        """

    27

    28

        self.label = label

    29

        self.value = value

    30

    31

    def __str__ (self) :

    32

        return "%s=%r" % (self.label.key, self.value)

    33

    34

    def __repr__ (self) :

    35

        return "<%s>" % self

    36

    37

class Label (object) :

    38

    """

    39

        Base class for URL labels (i.e. the segments of the URL between /s)

    40

    """

    41

    42

    @staticmethod

    43

    def parse (mask, defaults, types) :

    44

        """

    45

            Parse the given label-segment, and return a *Label instance

    46

        """

    47

    48

        # empty?

    49

        if not mask :

    50

            return EmptyLabel()

    51

    52

        # simple value?

    53

        match = SimpleValueLabel.EXPR.match(mask)

    54

    55

        if match :

    56

            # key

    57

            key = match.group('key')

    58

    59

            # type

    60

            type = match.group("type")

    61

    62

            # lookup type, None for default

    63

            type = types[type]

    64

    65

            # defaults?

    66

            default = defaults.get(key)

    67

    68

            if not default :

    69

                default = match.group('default')

    70

    71

                if default :

    72

                    # apply type to default

    73

                    default = type(default)

    74

    75

            # build

    76

            return SimpleValueLabel(key, type, default)

    77

    78

        # static?

    79

        match = StaticLabel.EXPR.match(mask)

    80

    81

        if match :

    82

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

    83

    84

        # invalid

    85

        raise URLError("Invalid label: %r" % (mask, ))

    86

    87

    def match (self, value=None) :

    88

        """

    89

            Match this label against the given value, returning either True to match without a value, a LabelValue

    90

            object, or boolean false to not match.

    91

    92

            If value is None, this means that only a default value should be returned.

    93

        """

    94

    95

        abstract

   103

   104

class EmptyLabel (Label) :

   105

    """

   106

        An empty label, i.e. just a slash in the URL

   107

    """

   108

   109

    def __eq__ (self, other) :

   110

        """

   111

            Just compares type

   112

        """

   113

   114

        return isinstance(other, EmptyLabel)

   115

   116

    def match (self, value=None) :

   117

        """

   118

            Match empty string -> True

   119

        """

   120

   121

        # no default

   122

        if value is None :

   123

            return False

   124

   125

        # only empty segments

   126

        if value == '' :

   127

            return True

   131

   132

    def __str__ (self) :

   133

        return ''

   134

   135

class StaticLabel (Label) :

   136

    """

   137

        A simple literal Label, used for fixed terms in the URL

   138

    """

   139

   140

    EXPR = re.compile(r'^(?P<name>[a-zA-Z_.-]+)$')

   141

   142

    def __init__ (self, name) :

   143

        """

   144

            The given name is the literal name of this label

   145

        """

   146

   147

        self.name = name

   148

   149

    def __eq__ (self, other) :

   150

        """

   151

            Compares names

   152

        """

   153

   154

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

   155

   156

    def match (self, value=None) :

   157

        """

   158

            Match exactly -> True

   159

        """

   160

   161

        # no defaults

   162

        if value is None :

   163

            return False

   164

   165

        # match name

   166

        if value == self.name :

   167

            return True

   168

   172

    def __str__ (self) :

   173

        return self.name

   174

   175

class ValueLabel (Label) :

   176

    """

   177

        A label with a key and a value

   178

   179

        XXX: do we even need this?

   180

    """

   181

   182

    def __init__ (self, key, default) :

   183

        """

   184

            Set the key and default value. Default value may be None if there is no default value defined

   185

        """

   186

   187

        self.key = key

   188

        self.default = default

   189

   190

    def __eq__ (self, other) :

   191

        """

   192

            Compares keys

   193

        """

   194

   195

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

   211

   212

class SimpleValueLabel (ValueLabel) :

   213

    """

   214

        A label that has a name and a simple string value

   215

    """

   216

   217

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

   218

   219

    def __init__ (self, key, type=str, default=None) :

   220

        """

   221

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

   222

        """

   223

   224

        # type

   225

        self.type = type

   226

   227

        # store

   228

        self.key = key

   229

        self.default = default

   230

   231

    def match (self, value=None) :

   232

        """

   233

            Match -> LabelValue

   234

        """

   235

   236

        # default?

   237

        if value is None and self.default :

   238

            return LabelValue(self, self.default)

   239

   240

        # only non-empty values!

   241

        elif value :

   242

            # convert with type

   243

            try :

   244

                value = self.type(value)

   245

   246

            except Exception, e :

   247

                raise URLError("Bad value %r for type %s: %s: %s" % (value, self.type.__name__, type(e).__name__, e))

   248

   249

            return LabelValue(self, value)

   250

   251

    def __str__ (self) :

   252

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

   253

            self.key, 

   254

            ':%s' % (self.type.__name__ ) if self.type != str else '',

   255

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

   256

        )

   257

   258

class URLConfig (object) :

   259

    """

   260

        Global configuration relevant to all URLs

   261

    """

   262

   263

    # built-in type codes

   264

    BUILTIN_TYPES = {

   265

        # default

   266

        None    : str,

   267

   268

        # integer

   269

        'int'   : int,

   270

    }

   271

   272

    def __init__ (self, type_dict=None) :

   273

        """

   274

            Create an URLConfig for use with URL

   275

   276

            If type_dict is given, it should be a mapping of type names -> callables, and they will be available for

   277

            type specifications in addition to the defaults.

   278

        """

   279

   280

        # build our type_dict

   281

        self.type_dict = self.BUILTIN_TYPES.copy()

   282

   283

        # apply the given type_dict

   284

        if type_dict :

   285

            self.type_dict.update(type_dict)

   286

   287

class URL (object) :

   288

    """

   289

        Represents a specific URL

   290

    """

   291

   292

   293

    def __init__ (self, config, url_mask, handler, type_dict=None, **defaults) :

   294

        """

   295

            Create an URL using the given URLConfig, with the given url mask, handler, and default values.

   296

        """

   297

   298

        # store

   299

        self.config = config

   300

        self.url_mask = url_mask

   301

        self.handler = handler

   302

        self.defaults = defaults

   303

   316

        self.label_path = [Label.parse(mask, defaults, config.type_dict) for mask in url_mask.split('/')]

   341

    def get_label_path (self) :

   342

        """

   343

            Returns a list containing the labels in this url

   344

        """

   345

   346

        # copy self.label_path

   347

        return list(self.label_path)

   348

   349

    def execute (self, request, label_values) :

   350

        """

   351

            Invoke the handler, using the given label values

   352

        """

   353

   354

        # start with the defaults

   355

        kwargs = self.defaults.copy()

   356

   357

        # then add all the values

   358

        for label_value in label_values :

   359

            kwargs[label_value.label.key] = label_value.value

   386

   390

        # execute the handler

   391

        return self.handler(request, **kwargs)

   400

   401

    def __str__ (self) :

   402

        return '/'.join(str(label) for label in self.label_path)

   403

   404

    def __repr__ (self) :

   405

        return "URL(%r, %r)" % (str(self), self.handler)

   406

   407

class URLNode (object) :

   408

    """

   409

        Represents a node in the URLTree

   410

    """

   411

   412

    def __init__ (self, parent, label) :

   413

        """

   414

            Initialize with the given parent and label, empty children dict

   415

        """

   416

   417

        # the parent URLNode

   418

        self.parent = parent

   419

   420

        # this node's Label

   421

        self.label = label

   422

   423

        # list of child URLNodes

   424

        self.children = []

   425

   426

        # this node's URL, set by add_url for an empty label_path

   427

        self.url = None

   428

   429

    def _build_child (self, label) :

   430

        """

   431

            Build, insert and return a new child Node

   432

        """

   433

   434

        # build new child

   435

        child = URLNode(self, label)

   436

   437

        # add to children

   438

        self.children.append(child)

   439

   440

        # return

   441

        return child

   442

   443

    def add_url (self, url, label_path) :

   444

        """

   445

            Add a URL object to this node under the given path. Uses recursion to process the path.

   446

   447

            The label_path argument is a (partial) label path as returned by URL.get_label_path.

   448

   449

            If label_path is empty (len zero, or begins with EmptyLabel), then the given url is assigned to this node, if no

   450

            url was assigned before.

   451

        """

   452

   453

        # matches this node?

   454

        if not label_path or isinstance(label_path[0], EmptyLabel) :

   455

            if self.url :

   456

                raise URLError(url, "node already defined")

   457

   458

            else :

   459

                # set

   460

                self.url = url

   461

   462

        else :

   463

            # pop child label from label_path

   464

            child_label = label_path.pop(0)

   465

   466

            # look for the child to recurse into

   467

            child = None

   468

   469

            # look for an existing child with that label

   470

            for child in self.children :

   471

                if child.label == child_label :

   472

                    # found, use this

   473

                    break

   474

   475

            else :

   476

                # build a new child

   477

                child = self._build_child(child_label)

   478

   479

            # recurse to handle the rest of the label_path

   480

            child.add_url(url, label_path)

   481

   482

    def match (self, label_path) :

   483

        """

   484

            Locate the URL object corresponding to the given label_path value under this node.

   485

   486

            Returns a (url, label_values) tuple

   487

        """

   488

   489

        # determine value to use

   490

        value = None

   491

   492

        # empty label_path?

   493

        if not label_path or label_path[0] == '' :

   494

            # the search ends at this node

   495

            if self.url :

   496

                # this URL is the best match

   497

                return (self.url, [])

   498

   499

            elif not self.children :

   500

                # incomplete URL

   501

                raise URLError("no URL handler defined for this Node")

   502

   503

            else :

   504

                # use default value, i.e. Label.match(None)

   505

                label = None

   506

   507

        else :

   508

            # pop the next label from the label path

   509

            label = label_path.pop(0)

   510

   511

        # return one match...

   512

        match = value = None

   513

   514

        # recurse through our children, DFS

   515

        for child in self.children :

   516

            # match value

   517

            value = child.label.match(label)

   518