1

"""

     2

    Tree-based URL mapping

     3

"""

     4

     5

import re

     6

import os.path

     7

     8

from qmsk.web import map

     9

    10

class URLError (Exception) :

    11

    """

    12

        Error with an URL definition

    13

    """

    14

    15

    pass

    16

    17

class LabelValue (object) :

    18

    """

    19

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

    20

    """

    21

    23

        """

    24

            Just store

    25

        """

    26

    27

        self.label = label

    28

        self.value = value

    30

    31

    def __str__ (self) :

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

    44

        """

    45

            Parse the given label-segment, and return a *Label instance. Config is the URLConfig to use

    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_name = match.group("type")

    61

    62

            # lookup type, None -> default

    63

            type = config.get_type(type_name)

    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.parse(default)

    74

    75

            # build

    76

            return SimpleValueLabel(key, type_name, 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

    def build (self, value_dict) :

    98

        """

    99

            Return a string representing this label, using the values in the given value_dict if needed

   100

        """

   101

   102

        abstract

   103

   112

class EmptyLabel (Label) :

   113

    """

   114

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

   115

    """

   116

   117

    def __eq__ (self, other) :

   118

        """

   119

            Just compares type

   120

        """

   121

   122

        return isinstance(other, EmptyLabel)

   123

   124

    def match (self, value=None) :

   125

        """

   126

            Match empty string -> True

   127

        """

   128

   129

        # no default

   130

        if value is None :

   131

            return False

   132

   133

        # only empty segments

   134

        if value == '' :

   135

            return True

   136

   137

    def build (self, values) :

   142

   143

    def __str__ (self) :

   144

        return ''

   145

   146

class StaticLabel (Label) :

   147

    """

   148

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

   149

    """

   150

   151

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

   152

   153

    def __init__ (self, name) :

   154

        """

   155

            The given name is the literal name of this label

   156

        """

   157

   158

        self.name = name

   159

   160

    def __eq__ (self, other) :

   161

        """

   162

            Compares names

   163

        """

   164

   165

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

   166

   167

    def match (self, value=None) :

   168

        """

   169

            Match exactly -> True

   170

        """

   171

   172

        # no defaults

   173

        if value is None :

   174

            return False

   175

   176

        # match name

   177

        if value == self.name :

   178

            return True

   179

   180

    def build (self, values) :

   185

   186

    def __str__ (self) :

   187

        return self.name

   188

   189

class ValueLabel (Label) :

   190

    """

   191

        A label with a key and a value

   192

   193

        XXX: do we even need this?

   194

    """

   195

   196

    def __init__ (self, key, default) :

   197

        """

   198

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

   199

        """

   200

   201

        self.key = key

   202

        self.default = default

   203

   204

    def __eq__ (self, other) :

   205

        """

   206

            Compares keys

   207

        """

   208

   209

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

   210

   211

    def build (self, values) :

   212

        """

   213

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

   214

        """

   215

   216

        # lookup the value obj to use

   217

        value = values.get(self.key)

   218

   220

            value = self.default

   221

   222

        elif not value :

   223

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

   224

   225

        # convert value back to str

   226

        value = self.type.build(value)

   227

   228

        return value

   229

   257

class SimpleValueLabel (ValueLabel) :

   258

    """

   259

        A label that has a name and a simple string value

   260

    """

   261

   262

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

   263

   264

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

   265

        """

   266

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

   267

   268

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

   269

        """

   270

   271

        # type

   272

        self.type_name = type_name

   273

        self.type = type

   274

   275

        # store

   276

        self.key = key

   277

        self.default = default

   278

   279

    def match (self, value=None) :

   280

        """

   281

            Match -> LabelValue

   282

        """

   283

   284

        # default?

   285

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

   287

   288

        # only non-empty values!

   289

        elif value :

   290

            # test

   291

            if not self.type.test(value) :

   292

                return False

   293

   294

            # convert with type

   295

            value = self.type.parse(value)

   296

   298

   299

    def __str__ (self) :

   300

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

   301

            self.key, 

   302

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

   303

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

   304

        )

   305

   306

class URLType (object) :

   307

    """

   308

        Handles the type-ness of values in the URL

   309

    """

   310

   311

    def test (self, value) :

   312

        """

   313

            Tests if the given value is valid for this type.

   314

   315

            Defaults to calling parse(), and returning False on errors, True otherwise

   316

        """

   317

   318

        try :

   319

            self.parse(value)

   320

   321

        except :

   322

            return False

   323

   324

        else :

   325

            return True

   326

   327

    def parse (self, value) :

   328

        """

   329

            Parse the given value, which was tested earlier with test(), and return the value object

   330

        """

   331

   332

        abstract

   333

   334

   335

    def build (self, obj) :

   336

        """

   337

            Reverse of parse(), return an url-value built from the given object

   338

        """

   339

   340

        abstract

   341

   342

class URLStringType (URLType) :

   343

    """

   344

        The default URLType, just plain strings.

   345

   346

        Note that this does not accept empty strings as valid

   347

    """

   348

   349

    def parse (self, value) :

   350

        """

   351

            Identitiy

   352

        """

   353

   354

        return value

   355

   356

    def build (self, obj) :

   357

        if not obj :

   358

            raise ValueError("String must not be empty")

   359

   360

        return str(obj)

   361

   362

class URLIntegerType (URLType) :

   363

    """

   364

        A URLType for simple integers

   365

    """

   366

   367

    def __init__ (self, allow_negative=True, allow_zero=True, max=None) :

   368

        """

   369

            Pass in allow_negative=False to disallow negative numbers, allow_zero=False to disallow zero, or non-zero

   370

            max to specifiy maximum value

   371

        """

   372

   373

        self.allow_negative = allow_negative

   374

        self.allow_zero = allow_zero

   375

        self.max = max

   376

   377

    def _validate (self, value) :

   378

        """

   379

            Test to make sure value fits our criteria

   380

        """

   381

   382

        # negative?

   383

        if not self.allow_negative and value < 0 :

   384

            raise ValueError("value is negative")

   385

   386

        # zero?

   387

        if not self.allow_zero and value == 0 :

   388

            raise ValueError("value is zero")

   389

   390

        # max?

   391

        if self.max is not None and value > max :

   392

            raise ValueError("value is too large: %d" % value)

   393

   394

        return value

   395

   396

    def parse (self, value) :

   397

        """

   398

            Convert str -> int

   399

        """

   400

   401

        return self._validate(int(value))

   402

   403

    def build (self, obj) :

   404

        """

   405

            Convert int -> str

   406

        """

   407

   408

        return unicode(self._validate(obj))

   409

   410

class URLConfig (object) :

   411

    """

   412

        Global configuration relevant to all URLs. This can be used to construct a set of URLs and then create an

   413

        URLTree out of them. Simply call the url_config() instace with the normal URL arguments (except, of course,

   414

        config), and finally just pass the url_config to URLTree (it's iterable).

   415

   416

        XXX: rename to URLFactory?

   417

    """

   418

   419

    # built-in type codes

   420

    BUILTIN_TYPES = {

   421

        # default - string

   422

        None    : URLStringType(),

   423

   424

        # string

   425

        'str'   : URLStringType(),

   426

   427

        # integer

   428

        'int'   : URLIntegerType(),

   429

    }

   430

   431

    def __init__ (self, type_dict=None, ignore_extra_args=True) :

   432

        """

   433

            Create an URLConfig for use with URL

   434

   435

            If type_dict is given, it should be a dict of { type_names: URLType }, and they will be available for

   436

            type specifications in addition to the defaults. This will call type._init_name with the key, so do

   437

            *not* initialize the name yourself.

   438

   439

            If ignore_extra_args is given, unrecognized query arguments will be ignored.

   440

        """

   441

   442

        # build our type_dict

   443

        self.type_dict = self.BUILTIN_TYPES.copy()

   444

   445

        # apply the given type_dict

   446

        if type_dict :

   447

            # merge

   448

            self.type_dict.update(type_dict)

   449

   450

        # init

   451

        self.ignore_extra_args = ignore_extra_args

   452

        self.urls = []

   453

   454

    def get_type (self, type_name=None) :

   455

        """

   456

            Lookup an URLType by type_name, None for default.

   457

        """

   458

   459

        # lookup + return

   460

        return self.type_dict[type_name]

   461

   462

    def __call__ (self, *args, **kwargs) :

   463

        """

   464

            Return new URL object with this config and the given args, adding it to our list of urls

   465

        """

   466

   467

        # build

   468

        url = URL(self, *args, **kwargs)

   469

   470

        # store

   471

        self.urls.append(url)

   472

   473

        # return

   474

        return url

   475

   476

    def __iter__ (self) :

   477

        """

   478

            Returns all defined URLs

   479

        """

   480

   481

        return iter(self.urls)

   482

   483

class URL (object) :

   484

    """

   485

        Represents a specific URL

   486

    """

   487

   488

   489

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

   490

        """

   491

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

   492

        """

   493

   494

        # store

   495

        self.config = config

   496

        self.url_mask = url_mask

   497

        self.handler = handler

   498

        self.defaults = defaults

   499

   500

        # query string

   501

        self.query_args = dict()