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

    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

    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

    96

    97

class EmptyLabel (Label) :

    98

    """

    99

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

   100

    """

   101

   102

    def __eq__ (self, other) :

   103

        """

   104

            Just compares type

   105

        """

   106

   107

        return isinstance(other, EmptyLabel)

   108

   109

    def match (self, value=None) :

   110

        """

   111

            Match empty string -> True

   112

        """

   113

   114

        # no default

   115

        if value is None :

   116

            return False

   117

   118

        # only empty segments

   119

        if value == '' :

   120

            return True

   121

   122

    def __str__ (self) :

   123

        return ''

   124

   125

class StaticLabel (Label) :

   126

    """

   127

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

   128

    """

   129

   130

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

   131

   132

    def __init__ (self, name) :

   133

        """

   134

            The given name is the literal name of this label

   135

        """

   136

   137

        self.name = name

   138

   139

    def __eq__ (self, other) :

   140

        """

   141

            Compares names

   142

        """

   143

   144

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

   145

   146

    def match (self, value=None) :

   147

        """

   148

            Match exactly -> True

   149

        """

   150

   151

        # no defaults

   152

        if value is None :

   153

            return False

   154

   155

        # match name

   156

        if value == self.name :

   157

            return True

   158

   159

    def __str__ (self) :

   160

        return self.name

   161

   162

class ValueLabel (Label) :

   163

    """

   164

        A label with a key and a value

   165

   166

        XXX: do we even need this?

   167

    """

   168

   169

    def __init__ (self, key, default) :

   170

        """

   171

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

   172

        """

   173

   174

        self.key = key

   175

        self.default = default

   176

   177

    def __eq__ (self, other) :

   178

        """

   179

            Compares keys

   180

        """

   181

   182

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

   183

   184

class SimpleValueLabel (ValueLabel) :

   185

    """

   186

        A label that has a name and a simple string value

   187

    """

   188

   189

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

   190

   191

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

   192

        """

   193

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

   194

        """

   195

   196

        # type

   197

        self.type = type

   198

   199

        # store

   200

        self.key = key

   201

        self.default = default

   202

   203

    def match (self, value=None) :

   204

        """

   205

            Match -> LabelValue

   206

        """

   207

   208

        # default?

   209

        if value is None and self.default :

   210

            return LabelValue(self, self.default)

   211

   212

        # only non-empty values!

   213

        elif value :

   214

            # convert with type

   215

            try :

   216

                value = self.type(value)

   217

   218

            except Exception, e :

   220

   221

            return LabelValue(self, value)

   222

   223

    def __str__ (self) :

   224

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

   225

            self.key, 

   226

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

   227

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

   228

        )

   259

class URL (object) :

   260

    """

   261

        Represents a specific URL

   262

    """

   263

   266

        """

   268

        """

   269

   270

        # store

   272

        self.url_mask = url_mask

   273

        self.handler = handler

   274

        self.defaults = defaults

   275

   276

        # build our labels

   278

   279

    def get_label_path (self) :

   280

        """

   281

            Returns a list containing the labels in this url

   282

        """

   283

   284

        # copy self.label_path

   285

        return list(self.label_path)

   286

   287

    def execute (self, request, label_values) :

   288

        """

   289

            Invoke the handler, using the given label values

   290

        """

   291

   292

        # start with the defaults

   293

        kwargs = self.defaults.copy()

   294

   295

        # then add all the values

   296

        for label_value in label_values :

   297

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

   298

   299

        # execute the handler

   300

        return self.handler(request, **kwargs)

   301

   302

    def __str__ (self) :

   303

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

   304

   305

    def __repr__ (self) :

   306

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

   307

   308

class URLNode (object) :

   309

    """

   310

        Represents a node in the URLTree

   311

    """

   312

   313

    def __init__ (self, parent, label) :

   314

        """

   315

            Initialize with the given parent and label, empty children dict

   316

        """

   317

   318

        # the parent URLNode

   319

        self.parent = parent

   320

   321

        # this node's Label

   322

        self.label = label

   323

   324

        # list of child URLNodes

   325

        self.children = []

   326

   327

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

   328

        self.url = None

   329

   330

    def _build_child (self, label) :

   331

        """

   332

            Build, insert and return a new child Node

   333

        """

   334

   335

        # build new child

   336

        child = URLNode(self, label)

   337

   338

        # add to children

   339

        self.children.append(child)

   340

   341

        # return

   342

        return child

   343

   344

    def add_url (self, url, label_path) :

   345

        """

   346

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

   347

   348

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

   349

   350

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

   351

            url was assigned before.

   352

        """

   353

   354

        # matches this node?

   355

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

   356

            if self.url :

   357

                raise URLError(url, "node already defined")

   358

   359

            else :

   360

                # set

   361

                self.url = url

   362

   363

        else :

   364

            # pop child label from label_path

   365

            child_label = label_path.pop(0)

   366

   367

            # look for the child to recurse into

   368

            child = None

   369

   370

            # look for an existing child with that label

   371

            for child in self.children :

   372

                if child.label == child_label :

   373

                    # found, use this

   374

                    break

   375

   376

            else :

   377

                # build a new child

   378

                child = self._build_child(child_label)

   379

   380

            # recurse to handle the rest of the label_path

   381

            child.add_url(url, label_path)

   382

   383

    def match (self, label_path) :

   384

        """

   385

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

   386

   387

            Returns a (url, label_values) tuple

   388

        """

   389

   390

        # determine value to use

   391

        value = None

   392

   393

        # empty label_path?

   394

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

   395

            # the search ends at this node

   396

            if self.url :

   397

                # this URL is the best match

   398

                return (self.url, [])

   399

   400

            elif not self.children :

   401

                # incomplete URL

   402

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

   403

   404

            else :

   405

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

   406

                label = None

   407

   408

        else :

   409

            # pop the next label from the label path

   410

            label = label_path.pop(0)

   411

   412

        # return one match...

   413

        match = value = None

   414

   415

        # recurse through our children, DFS

   416

        for child in self.children :

   417

            # match value

   418

            value = child.label.match(label)

   419

   420

            # skip those that don't match at all

   421

            if not value :

   422

                continue;

   423

   424

            # already found a match? :/

   425

            if match :

   426

                raise URLError("Ambiguous URL")

   427

   428

            # ok, but continue looking to make sure there's no ambiguous URLs

   429

            match = child

   430

   431

        # found something?

   432

        if not match :

   433

            raise URLError("No child found for label: %s + %s + %s" % (self.get_url(), label, '/'.join(str(l) for l in label_path)))

   434

   435

        # ok, recurse into the match

   436

        url, label_value = match.match(label_path)

   437

   438

        # add our value?

   439

        if isinstance(value, LabelValue) :

   440

            label_value.append(value)

   441

   442

        # return the match

   443

        return url, label_value

   444

   445

    def get_url (self) :

   446

        """

   447

            Returns the URL for this node, by iterating over our parents

   448

        """

   449

   450

        # URL segments in reverse order

   451

        segments = ['']

   452

   453

        # start with ourself

   454

        node = self

   455

   456

        # iterate up to root

   457

        while node :

   458

            segments.append(str(node.label))

   459

   460

            node = node.parent

   461

   462

        # reverse

   463

        segments.reverse()

   464

   465

        # return

   466

        return '/'.join(segments)

   467

   468

    def dump (self, indent=0) :

   469

        """

   470

            Returns a multi-line string representation of this Node

   471

        """

   472

   473

        return '\n'.join([

   474

            "%-45s%s" % (

   475

                ' '*indent + str(self.label) + ('/' if self.children else ''), 

   476

                (' -> %r' % self.url) if self.url else ''

   477

            )

   478

        ] + [

   479

            child.dump(indent + 4) for child in self.children

   480

        ])

   481

   482

    def __str__ (self) :

   483

        return "%s/[%s]" % (self.label, ','.join(str(child) for child in self.children))

   484

   485

class URLTree (map.Mapper) :

   486

    """

   487

        Map requests to handlers, using a defined tree of URLs

   488

    """

   489

   490

    def __init__ (self, url_list) :

   491

        """

   492

            Initialize the tree using the given list of URLs

   493

        """

   494

   495

        # root node

   496

        self.root = URLNode(None, EmptyLabel())

   497

   498

        # just add each URL

   499

        for url in url_list :

   500

            self.add_url(url)

   501

   502

    def add_url (self, url) :

   503

        """

   504

            Adds the given URL to the tree. The URL must begin with a root slash.

   505

        """

   506

        # get url's label path

   507

        path = url.get_label_path()

   508

   509

        # should begin with root

   510

        root_label = path.pop(0)

   511

        assert root_label == self.root.label, "URL must begin with root"

   512

   513

        # add to root

   514

        self.root.add_url(url, path)

   515

   516

    def match (self, url) :

   517

        """

   518

            Find the URL object best corresponding to the given url, matching any ValueLabels.

   519

   520

            Returns an (URL, [LabelValue]) tuple.

   521

        """

   522

   523

        # split it into labels

   524