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) :

    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

            if type :

    63

                # XXX: resolve using eval() for now, should be a module or something

    64

                type = eval(type)

    65

    66

            else :

    67

                type = str

    68

    69

            # defaults?

    70

            default = defaults.get(key)

    71

    72

            if not default :

    73

                default = match.group('default')

    74

    75

                if default :

    76

                    # apply type to default

    77

                    default = type(default)

    78

    79

            # build

    80

            return SimpleValueLabel(key, type, default)

    81

    82

        # static?

    83

        match = StaticLabel.EXPR.match(mask)

    84

    85

        if match :

    86

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

    87

    88

        # invalid

    89

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

    90

    91

    def match (self, value=None) :

    92

        """

    93

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

    94

            object, or boolean false to not match.

    95

    96

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

    97

        """

    98

    99

        abstract

   100

   101

class EmptyLabel (Label) :

   102

    """

   103

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

   104

    """

   105

   106

    def __eq__ (self, other) :

   107

        """

   108

            Just compares type

   109

        """

   110

   111

        return isinstance(other, EmptyLabel)

   112

   113

    def match (self, value=None) :

   114

        """

   115

            Match empty string -> True

   116

        """

   117

   118

        # no default

   119

        if value is None :

   120

            return False

   121

   122

        # only empty segments

   123

        if value == '' :

   124

            return True

   125

   126

    def __str__ (self) :

   127

        return ''

   128

   129

class StaticLabel (Label) :

   130

    """

   131

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

   132

    """

   133

   134

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

   135

   136

    def __init__ (self, name) :

   137

        """

   138

            The given name is the literal name of this label

   139

        """

   140

   141

        self.name = name

   142

   143

    def __eq__ (self, other) :

   144

        """

   145

            Compares names

   146

        """

   147

   148

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

   149

   150

    def match (self, value=None) :

   151

        """

   152

            Match exactly -> True

   153

        """

   154

   155

        # no defaults

   156

        if value is None :

   157

            return False

   158

   159

        # match name

   160

        if value == self.name :

   161

            return True

   162

   163

    def __str__ (self) :

   164

        return self.name

   165

   166

class ValueLabel (Label) :

   167

    """

   168

        A label with a key and a value

   169

   170

        XXX: do we even need this?

   171

    """

   172

   173

    def __init__ (self, key, default) :

   174

        """

   175

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

   176

        """

   177

   178

        self.key = key

   179

        self.default = default

   180

   181

    def __eq__ (self, other) :

   182

        """

   183

            Compares keys

   184

        """

   185

   186

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

   187

   188

class SimpleValueLabel (ValueLabel) :

   189

    """

   190

        A label that has a name and a simple string value

   191

    """

   192

   193

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

   194

   195

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

   196

        """

   197

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

   198

        """

   199

   200

        # type

   201

        self.type = type

   202

   203

        # store

   204

        self.key = key

   205

        self.default = default

   206

   207

    def match (self, value=None) :

   208

        """

   209

            Match -> LabelValue

   210

        """

   211

   212

        # default?

   213

        if value is None and self.default :

   214

            return LabelValue(self, self.default)

   215

   216

        # only non-empty values!

   217

        elif value :

   218

            # convert with type

   219

            try :

   220

                value = self.type(value)

   221

   222

            except Exception, e :

   223

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

   224

   225

            return LabelValue(self, value)

   226

   227

    def __str__ (self) :

   228

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

   229

            self.key, 

   230

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

   231

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

   232

        )

   233

   234

class URL (object) :

   235

    """

   236

        Represents a specific URL

   237

    """

   238

   239

    def __init__ (self, url_mask, handler, **defaults) :

   240

        """

   241

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

   242

        """

   243

   244

        # store

   245

        self.url_mask = url_mask

   246

        self.handler = handler

   247

        self.defaults = defaults

   248

   249

        # build our labels

   250

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

   251

   252

    def get_label_path (self) :

   253

        """

   254

            Returns a list containing the labels in this url

   255

        """

   256

   257

        # copy self.label_path

   258

        return list(self.label_path)

   259

   260

    def execute (self, request, label_values) :

   261

        """

   262

            Invoke the handler, using the given label values

   263

        """

   264

   265

        # start with the defaults

   266

        kwargs = self.defaults()

   267

   268

        # then add all the values

   269

        for label_value in label_values :

   270

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

   271

   272

        # execute the handler

   273

        return self.handler(request, **kwargs)

   274

   275

    def __str__ (self) :

   276

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

   277

   278

    def __repr__ (self) :

   279

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

   280

   281

class URLNode (object) :

   282

    """

   283

        Represents a node in the URLTree

   284

    """

   285

   286

    def __init__ (self, parent, label) :

   287

        """

   288

            Initialize with the given parent and label, empty children dict

   289

        """

   290

   291

        # the parent URLNode

   292

        self.parent = parent

   293

   294

        # this node's Label

   295

        self.label = label

   296

   297

        # list of child URLNodes

   298

        self.children = []

   299

   300

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

   301

        self.url = None

   302

   303

    def _build_child (self, label) :

   304

        """

   305

            Build, insert and return a new child Node

   306

        """

   307

   308

        # build new child

   309

        child = URLNode(self, label)

   310

   311

        # add to children

   312

        self.children.append(child)

   313

   314

        # return

   315

        return child

   316

   317

    def add_url (self, url, label_path) :

   318

        """

   319

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

   320

   321

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

   322

   323

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

   324

            url was assigned before.

   325

        """

   326

   327

        # matches this node?

   328

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

   329

            if self.url :

   330

                raise URLError(url, "node already defined")

   331

   332

            else :

   333

                # set

   334

                self.url = url

   335

   336

        else :

   337

            # pop child label from label_path

   338

            child_label = label_path.pop(0)

   339

   340

            # look for the child to recurse into

   341

            child = None

   342

   343

            # look for an existing child with that label

   344

            for child in self.children :

   345

                if child.label == child_label :

   346

                    # found, use this

   347

                    break

   348

   349

            else :

   350

                # build a new child

   351

                child = self._build_child(child_label)

   352

   353

            # recurse to handle the rest of the label_path

   354

            child.add_url(url, label_path)

   355

   356

    def match (self, label_path) :

   357

        """

   358

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

   359

   360

            Returns a (url, label_values) tuple

   361

        """

   362

   363

        # determine value to use

   364

        value = None

   365

   366

        # empty label_path?

   367

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

   368

            # the search ends at this node

   369

            if self.url :

   370

                # this URL is the best match

   371

                return (self.url, [])

   372

   373

            elif not self.children :

   374

                # incomplete URL

   375

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

   376

   377

            else :

   378

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

   379

                label = None

   380

   381

        else :

   382

            # pop the next label from the label path

   383

            label = label_path.pop(0)

   384

   385

        # return one match...

   386

        match = value = None

   387

   388

        # recurse through our children, DFS

   389

        for child in self.children :

   390

            # match value

   391

            value = child.label.match(label)

   392

   393

            # skip those that don't match at all

   394

            if not value :

   395

                continue;

   396

   397

            # already found a match? :/

   398

            if match :

   399

                raise URLError("Ambiguous URL")

   400

   401

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

   402

            match = child

   403

   404

        # found something?

   405

        if not match :

   406

            raise URLError("No child found for label")

   407

   408

        # ok, recurse into the match

   409

        url, label_value = match.match(label_path)

   410

   411

        # add our value?

   412

        if isinstance(value, LabelValue) :

   413

            label_value.append(value)

   414

   415

        # return the match

   416

        return url, label_value

   417

   418

    def dump (self, indent=0) :

   419

        """

   420

            Returns a multi-line string representation of this Node

   421

        """

   422

   423

        return '\n'.join([

   424

            "%-45s%s" % (

   425

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

   426

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

   427

            )

   428

        ] + [

   429

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

   430

        ])

   431

   432

    def __str__ (self) :

   433

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

   434

   435

class URLTree (map.Mapper) :

   436

    """

   437

        Map requests to handlers, using a defined tree of URLs

   438

    """

   439

   440

    def __init__ (self, url_list) :

   441

        """

   442

            Initialize the tree using the given list of URLs

   443

        """

   444

   445

        # root node

   446

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

   447

   448

        # just add each URL

   449

        for url in url_list :

   450

            self.add_url(url)

   451

   452

    def add_url (self, url) :

   453

        """

   454

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

   455

        """

   456

        # get url's label path

   457

        path = url.get_label_path()

   458

   459

        # should begin with root

   460

        root_label = path.pop(0)

   461

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

   462

   463

        # add to root

   464

        self.root.add_url(url, path)

   465

   466

    def match (self, url) :

   467

        """

   468

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

   469

   470

            Returns an (URL, [LabelValue]) tuple.

   471

        """

   472

   473

        # normalize the URL

   474

        url = os.path.normpath(url)

   475

   476

        # split it into labels

   477

        path = url.split('/')

   478

   479

        # ensure that it starts with a /

   480

        root_label = path.pop(0)

   481

        assert self.root.label.match(root_label), "URL must begin with root"

   482

   483

        # just match starting at root

   484

        return self.root.match(path)

   485

   486

    def handle_request (self, request) :

   487

        """

   488

            Looks up the request's URL, and invokes its handler

   489

        """

   490

   491

        # get the request's URL path

   492

        url, label_values = self.match(request.get_page_name())

   493

   494

        # let the URL handle it

   495

        url.execute(request, label_values)

   496

   497